From 8815be2af34a15c2e9c36f17c7a5f66c30a756e0 Mon Sep 17 00:00:00 2001 From: Mike Fiedler Date: Tue, 30 Mar 2021 16:18:57 -0400 Subject: [PATCH] chore: replace rst with markdown As tooling improves for Markdown, and it becomes a ubiquitous syntax, convert our documentation over to that format. Includes minor changes to content, such as ordering and formatting. Resolves #59 Signed-off-by: Mike Fiedler --- CHANGELOG.md | 65 ++++++++++++++++++++ CHANGELOG.rst | 76 ----------------------- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++ README.rst | 162 ------------------------------------------------- pyproject.toml | 4 +- 5 files changed, 206 insertions(+), 240 deletions(-) create mode 100644 CHANGELOG.md delete mode 100644 CHANGELOG.rst create mode 100644 README.md delete mode 100644 README.rst diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d7bf379 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,65 @@ +# pytest-socket change log + +This document records all notable changes to +[pytest-socket](https://pypi.python.org/pypi/pytest-socket). This +project attempts to adhere to [Semantic Versioning](http://semver.org/). + +## [0.3.5][] (2020-05-31) + +Bugfix release. + +- Fix bug in marker evaluation \#42 +- Refactor tests for clarity + +## [0.3.4][] (2020-04-10) + +Maintenance release. + +- Drop support for unsupported versions of Python #23 +- Convert toolchain from pip/tox/twine to poetry +- Replace TravisCI and Appveyor with GitHub Actions #36 +- Update for correct test output #31 +- Add renovatebot for dependecy updates #26 + +## [0.3.3][] (2019-02-09) + +- Fix hostname check when unicode on Python 2.7.x #22 + +## [0.3.2][] (2019-01-07) + +- Update support for Pytest 4.1.x +- Test package on Python 3.7.x +- Stop testing on pypy + +## [0.3.1][] (2018-07-16) + +- Update minimum required pytest version + +## [0.3.0][] (2018-07-15) + +- Add support for allowing specific lists of hosts via IP Addresses +- Change the inherited exception class in tests +- Add codeclimate to travis output +- Add coverage reporting +- Drop support for Python 3.3 + +## [0.2.0][] (2017-07-15) + +- Reorganized API, requires explicit activation +- Added Python 3.x compatibility +- Added `ini` setting +- Test all Python versions +- Relax py.test version requirement + +## [0.1.0] (2017-06-01) + +- Initial public release + +[0.1.0]: https://github.com/miketheman/pytest-socket/releases/tag/0.1.0 +[0.2.0]: https://github.com/miketheman/pytest-socket/compare/0.1.0...0.2.0 +[0.3.0]: https://github.com/miketheman/pytest-socket/compare/0.2.0...0.3.0 +[0.3.1]: https://github.com/miketheman/pytest-socket/compare/0.3.0...0.3.1 +[0.3.2]: https://github.com/miketheman/pytest-socket/compare/0.3.1...0.3.2 +[0.3.3]: https://github.com/miketheman/pytest-socket/compare/0.3.2...0.3.3 +[0.3.4]: https://github.com/miketheman/pytest-socket/compare/0.3.3...0.3.4 +[0.3.5]: https://github.com/miketheman/pytest-socket/compare/0.3.4...0.3.5 diff --git a/CHANGELOG.rst b/CHANGELOG.rst deleted file mode 100644 index 66830ca..0000000 --- a/CHANGELOG.rst +++ /dev/null @@ -1,76 +0,0 @@ -============= -pytest-socket -============= - -This document records all notable changes to `pytest-socket `_. -This project attempts to adhere to `Semantic Versioning `_. - -`0.3.5`_ (2020-05-31) ---------------------- - -Bugfix release. - -* Fix bug in marker evaluation #42 -* Refactor tests for clarity - -`0.3.4`_ (2020-04-10) ---------------------- - -Maintenance release. - -* Drop support for unsupported versions of Python #23 -* Convert toolchain from pip/tox/twine to poetry -* Replace TravisCI and Appveyor with GitHub Actions #36 -* Update for correct test output #31 -* Add renovatebot for dependecy updates #26 - -`0.3.3`_ (2019-02-09) ---------------------- - -* Fix hostname check when unicode on Python 2.7.x #22 - -`0.3.2`_ (2019-01-07) ---------------------- - -* Update support for Pytest 4.1.x -* Test package on Python 3.7.x -* Stop testing on pypy - -`0.3.1`_ (2018-07-16) ---------------------- - -* Update minimum required pytest version - -`0.3.0`_ (2018-07-15) ---------------------- - -* Add support for allowing specific lists of hosts via IP Addresses -* Change the inherited exception class in tests -* Add codeclimate to travis output -* Add coverage reporting -* Drop support for Python 3.3 - -`0.2.0`_ (2017-07-15) ---------------------- - -* Reorganized API, requires explicit activation -* Added Python 3.x compatibility -* Added ``ini`` setting -* Test all Python versions -* Relax py.test version requirement - - -`0.1.0`_ (2017-06-01) ---------------------- - -* Initial public release - - -.. _0.1.0: https://github.com/miketheman/pytest-socket/releases/tag/0.1.0 -.. _0.2.0: https://github.com/miketheman/pytest-socket/compare/0.1.0...0.2.0 -.. _0.3.0: https://github.com/miketheman/pytest-socket/compare/0.2.0...0.3.0 -.. _0.3.1: https://github.com/miketheman/pytest-socket/compare/0.3.0...0.3.1 -.. _0.3.2: https://github.com/miketheman/pytest-socket/compare/0.3.1...0.3.2 -.. _0.3.3: https://github.com/miketheman/pytest-socket/compare/0.3.2...0.3.3 -.. _0.3.4: https://github.com/miketheman/pytest-socket/compare/0.3.3...0.3.4 -.. _0.3.5: https://github.com/miketheman/pytest-socket/compare/0.3.4...0.3.5 diff --git a/README.md b/README.md new file mode 100644 index 0000000..baa054b --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# pytest-socket + +[![PyPI current version](https://img.shields.io/pypi/v/pytest-socket.svg)](https://pypi.python.org/pypi/pytest-socket) +[![Python Support](https://img.shields.io/pypi/pyversions/pytest-socket.svg)](https://pypi.python.org/pypi/pytest-socket) +[![Tests](https://github.com/miketheman/pytest-socket/workflows/Python%20Tests/badge.svg)](https://github.com/miketheman/pytest-socket/actions?query=workflow%3A%22Python+Tests%22) +[![Maintainability](https://api.codeclimate.com/v1/badges/1608a75b1c3a20211992/maintainability)](https://codeclimate.com/github/miketheman/pytest-socket/maintainability) +[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_shield) + +A plugin to use with Pytest to disable or restrict `socket` calls during +tests to ensure network calls are prevented. + +--- + +## Features + +- Disables all network calls flowing through Python\'s `socket` interface. + +## Requirements + +- [Pytest](https://github.com/pytest-dev/pytest) 3.6.3 or greater + +## Installation + +You can install `pytest-socket` via [pip](https://pypi.python.org/pypi/pip/) +from [PyPI](https://pypi.python.org/pypi): + +```console +$ pip install pytest-socket +``` + +or add to your `pyproject.toml` for [poetry](https://python-poetry.org/): + +```ini +[tool.poetry.dev-dependencies] +pytest-socket = "*" +``` + +## Usage + +Run `pytest --disable-socket`, tests should fail on any access to `socket` or +libraries using socket with a `SocketBlockedError`. + +To add this flag as the default behavior, add this section to your +`pytest.ini` or `setup.cfg`: + +```ini +[pytest] +addopts = --disable-socket +``` + +or update your `conftest.py` to include: + +```python +from pytest_socket import disable_socket + +def pytest_runtest_setup(): + disable_socket() +``` + +To enable Unix sockets during the test run (e.g. for async), add this option: + +```ini +[pytest] +addopts = --disable-socket --allow-unix-socket +``` + +To enable specific tests use of `socket`, pass in the fixture to the test or +use a marker: + +```python +def test_explicitly_enable_socket(socket_enabled): + assert socket.socket(socket.AF_INET, socket.SOCK_STREAM) + + +@pytest.mark.enable_socket +def test_explicitly_enable_socket_with_mark(): + assert socket.socket(socket.AF_INET, socket.SOCK_STREAM) +``` + +To allow only specific hosts per-test: + +```python +@pytest.mark.allow_hosts(['127.0.0.1']) +def test_explicitly_enable_socket_with_mark(): + assert socket.socket.connect(('127.0.0.1', 80)) +``` + +or for whole test run + +```ini +[pytest] +addopts = --allow-hosts=127.0.0.1,127.0.1.1 +``` + +### Frequently Asked Questions + +Q: Why is network access disabled in some of my tests but not others? + +A: pytest's default fixture scope is "function", which `socket_enabled` uses. +If you create another fixture that creates a socket usage that has a "higher" +instantiation order, such as at the module/class/session, then the higher order +fixture will be resolved first, and won't be disabled during the tests. +Read more in [this excellent example](https://github.com/miketheman/pytest-socket/issues/45#issue-679835420) +and more about [pytest fixture order here](https://docs.pytest.org/en/stable/fixture.html#fixture-instantiation-order). + +This behavior may change in the future, as we learn more about pytest +fixture order, and what users expect to happen. + +## Contributing + +Contributions are very welcome. Tests can be run with +[pytest](https://github.com/pytest-dev/pytest), please ensure the +coverage at least stays the same before you submit a pull request. + +## License + +Distributed under the terms of the +[MIT](http://opensource.org/licenses/MIT) license, "pytest-socket" is +free and open source software + +[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_large) + +## Issues + +If you encounter any problems, please [file an issue](https://github.com/miketheman/pytest-socket/issues) +along with a detailed description. + +## References + +This [Pytest](https://github.com/pytest-dev/pytest) plugin was generated with +[Cookiecutter](https://github.com/audreyr/cookiecutter) along with +[\@hackebrot](https://github.com/hackebrot)\'s +[Cookiecutter-pytest-plugin](https://github.com/pytest-dev/cookiecutter-pytest-plugin) +template. + +This plugin came about due to the efforts by +[\@hangtwenty](https://github.com/hangtwenty) solving a [StackOverflow +question](https://stackoverflow.com/a/30064664), then converted into a +pytest plugin by [\@miketheman](https://github.com/miketheman). diff --git a/README.rst b/README.rst deleted file mode 100644 index fd3b455..0000000 --- a/README.rst +++ /dev/null @@ -1,162 +0,0 @@ -============= -pytest-socket -============= - -.. image:: https://img.shields.io/pypi/v/pytest-socket.svg - :target: https://pypi.python.org/pypi/pytest-socket - -.. image:: https://img.shields.io/pypi/pyversions/pytest-socket.svg - :target: https://pypi.python.org/pypi/pytest-socket - -.. image:: https://github.com/miketheman/pytest-socket/workflows/Python%20Tests/badge.svg - :target: https://github.com/miketheman/pytest-socket/actions?query=workflow%3A%22Python+Tests%22 - :alt: Python Tests - -.. image:: https://api.codeclimate.com/v1/badges/1608a75b1c3a20211992/maintainability - :target: https://codeclimate.com/github/miketheman/pytest-socket/maintainability - :alt: Maintainability - -.. image:: https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=shield - :target: https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_shield - :alt: FOSSA Status - - -A plugin to use with Pytest to disable or restrict ``socket`` calls during tests to ensure network calls are prevented. - ----- - -This `Pytest`_ plugin was generated with `Cookiecutter`_ along with `@hackebrot`_'s `Cookiecutter-pytest-plugin`_ template. - - -Features --------- - -* Disables all network calls flowing through Python's ``socket`` interface. - - -Requirements ------------- - -* `Pytest`_ 3.6.3 or greater - - -Installation ------------- - -You can install "pytest-socket" via `pip`_ from `PyPI`_:: - - $ pip install pytest-socket - - -Usage ------ - -* Run ``pytest --disable-socket``, tests should fail on any access to ``socket`` or libraries using - socket with a ``SocketBlockedError``. - - To add this flag as the default behavior, add this section to your ``pytest.ini`` or ``setup.cfg``: - - .. code:: ini - - [pytest] - addopts = --disable-socket - - - or update your ``conftest.py`` to include: - - .. code:: python - - from pytest_socket import disable_socket - - def pytest_runtest_setup(): - disable_socket() - -* To enable Unix sockets during the test run (e.g. for async), add this option: - -.. code:: ini - - [pytest] - addopts = --disable-socket --allow-unix-socket - -* To enable specific tests use of ``socket``, pass in the fixture to the test or use a marker: - - .. code:: python - - def test_explicitly_enable_socket(socket_enabled): - assert socket.socket(socket.AF_INET, socket.SOCK_STREAM) - - - @pytest.mark.enable_socket - def test_explicitly_enable_socket_with_mark(): - assert socket.socket(socket.AF_INET, socket.SOCK_STREAM) - -* To allow only specific hosts per-test: - - .. code:: python - - @pytest.mark.allow_hosts(['127.0.0.1']) - def test_explicitly_enable_socket_with_mark(): - assert socket.socket.connect(('127.0.0.1', 80)) - -or for whole test run - - .. code:: ini - - [pytest] - addopts = --allow-hosts=127.0.0.1,127.0.1.1 - -Frequently Asked Questions -========================== - -Q: Why is network access disabled in some of my tests but not others? - -A: pytest's default fixture scope is "function", which ``socket_enabled`` uses. -If you create another fixture that creates a socket usage that has a "higher" -instantiation order, such as at the module/class/session, then the higher -fixture will be resolved first, and won't be disabled during the tests. -Read more in `this excellent example -`_ and -more about `pytest fixture order here `_. - -This behavior may change in the future, as we learn more about pytest fixture -order, and what users expect to happen. - -Contributing ------------- -Contributions are very welcome. Tests can be run with `pytest`_, please ensure -the coverage at least stays the same before you submit a pull request. - -License -------- - -Distributed under the terms of the `MIT`_ license, "pytest-socket" is free and open source software - -.. image:: https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=large - :target: https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_large - :alt: FOSSA Status - -Issues ------- - -If you encounter any problems, please `file an issue`_ along with a detailed description. - - -References ----------- - -This plugin came about due to the efforts by `@hangtwenty`_ solving a `StackOverflow question`_, -then converted into a pytest plugin by `@miketheman`_. - - -.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter -.. _`@hackebrot`: https://github.com/hackebrot -.. _`MIT`: http://opensource.org/licenses/MIT -.. _`cookiecutter-pytest-plugin`: https://github.com/pytest-dev/cookiecutter-pytest-plugin -.. _`file an issue`: https://github.com/miketheman/pytest-socket/issues -.. _`pytest`: https://github.com/pytest-dev/pytest -.. _`tox`: https://tox.readthedocs.io/en/latest/ -.. _`pip`: https://pypi.python.org/pypi/pip/ -.. _`PyPI`: https://pypi.python.org/pypi -.. _`@hangtwenty`: https://github.com/hangtwenty -.. _`StackOverflow question`: https://stackoverflow.com/a/30064664 -.. _`@miketheman`: https://github.com/miketheman diff --git a/pyproject.toml b/pyproject.toml index b0bb58f..8f952d9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,12 +4,12 @@ version = "0.3.5" description = "Pytest Plugin to disable socket calls during tests" authors = ["Mike Fiedler "] license = "MIT" -readme = "README.rst" +readme = "README.md" homepage = "https://pypi.org/project/pytest-socket/" repository = "https://github.com/miketheman/pytest-socket" include = [ "LICENSE", - "README.rst", + "README.md", ] classifiers = [ "Development Status :: 4 - Beta",