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 <[email protected]>

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

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).