diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60c4da2a..d441849e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,22 @@ So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: ```bash -python setup.py develop && pip install -r requirements-dev.txt +pip3 install -e . "[.dev]" ``` +# Dependency Changes + +`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the +effort required in managing the dependencies. Please make sure you have read and understood the following section of +the document that explains the way `sanic` manages dependencies inside the `setup.py` file. + +| Dependency Type | Usage | Installation | +| ------------------------------------------| -------------------------------------------------------------------------- | --------------------------- | +| requirements | Bare minimum dependencies required for sanic to function | pip3 install -e . | +| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | pip3 install -e '[.test]' | +| extras_require['dev'] | Additional Development requirements to add contributing | pip3 install -e '[.dev]' | +| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | pip3 install -e '[.docs]' | + ## Running tests To run the tests for sanic it is recommended to use tox like so: diff --git a/docs/sanic/contributing.md b/docs/sanic/contributing.md deleted file mode 100644 index 0b527bb7..00000000 --- a/docs/sanic/contributing.md +++ /dev/null @@ -1,62 +0,0 @@ -# Contributing - -Thank you for your interest! Sanic is always looking for contributors. If you -don't feel comfortable contributing code, adding docstrings to the source files -is very appreciated. - -## Installation - -To develop on sanic (and mainly to just run the tests) it is highly recommend to -install from sources. - -So assume you have already cloned the repo and are in the working directory with -a virtual environment already set up, then run: - -```bash -python setup.py develop && pip install -r requirements-dev.txt -``` - -## Running tests - -To run the tests for sanic it is recommended to use tox like so: - -```bash -tox -``` - -See it's that simple! - -## Pull requests! - -So the pull request approval rules are pretty simple: -* All pull requests must pass unit tests -* All pull requests must be reviewed and approved by at least -one current collaborator on the project -* All pull requests must pass flake8 checks -* If you decide to remove/change anything from any common interface -a deprecation message should accompany it. -* If you implement a new feature you should have at least one unit -test to accompany it. - -## Documentation - -Sanic's documentation is built -using [sphinx](http://www.sphinx-doc.org/en/1.5.1/). Guides are written in -Markdown and can be found in the `docs` folder, while the module reference is -automatically generated using `sphinx-apidoc`. - -To generate the documentation from scratch: - -```bash -sphinx-apidoc -fo docs/_api/ sanic -sphinx-build -b html docs docs/_build -``` - -The HTML documentation will be created in the `docs/_build` folder. - -## Warning - -One of the main goals of Sanic is speed. Code that lowers the performance of -Sanic without significant gains in usability, security, or features may not be -merged. Please don't let this intimidate you! If you have any concerns about an -idea, open an issue for discussion and help. diff --git a/docs/sanic/contributing.rst b/docs/sanic/contributing.rst new file mode 100644 index 00000000..b9402da3 --- /dev/null +++ b/docs/sanic/contributing.rst @@ -0,0 +1,89 @@ +Contributing +============ + +Thank you for your interest! Sanic is always looking for contributors. +If you don’t feel comfortable contributing code, adding docstrings to +the source files is very appreciated. + +Installation +------------ + +To develop on sanic (and mainly to just run the tests) it is highly +recommend to install from sources. + +So assume you have already cloned the repo and are in the working +directory with a virtual environment already set up, then run: + +.. code:: bash + + pip3 install -e . '[.dev]' + +Dependency Changes +------------------ + +``Sanic`` doesn't use ``requirements*.txt`` files to manage any kind of dependencies related to it in order to simplify the +effort required in managing the dependencies. Please make sure you have read and understood the following section of +the document that explains the way ``sanic`` manages dependencies inside the ``setup.py`` file. + ++------------------------+-----------------------------------------------+----------------------------+ +| Dependency Type | Usage | Installation | ++========================+===============================================+============================+ +| requirements | Bare minimum dependencies required for sanic | pip3 install -e . | +| | to function | | ++------------------------+-----------------------------------------------+----------------------------+ +| tests_require / | Dependencies required to run the Unit Tests | pip3 install -e '[.test]' | +| extras_require['test'] | for ``sanic`` | | ++------------------------+-----------------------------------------------+----------------------------+ +| extras_require['dev'] | Additional Development requirements to add | pip3 install -e '[.dev]' | +| | contributing | | ++------------------------+-----------------------------------------------+----------------------------+ +| extras_require['docs'] | Dependencies required to enable building and |pip3 install -e '[.docs]' | +| | enhancing sanic documentation | | ++------------------------+-----------------------------------------------+----------------------------+ + +Running tests +------------- + +To run the tests for sanic it is recommended to use tox like so: + +.. code:: bash + + tox + +See it’s that simple! + +Pull requests! +-------------- + +So the pull request approval rules are pretty simple: + +* All pull requests must pass unit tests +* All pull requests must be reviewed and approved by at least one current collaborator on the project +* All pull requests must pass flake8 checks +* If you decide to remove/change anything from any common interface a deprecation message should accompany it. +* If you implement a new feature you should have at least one unit test to accompany it. + +Documentation +------------- + +Sanic’s documentation is built using `sphinx`_. Guides are written in +Markdown and can be found in the ``docs`` folder, while the module +reference is automatically generated using ``sphinx-apidoc``. + +To generate the documentation from scratch: + +.. code:: bash + + sphinx-apidoc -fo docs/_api/ sanic + sphinx-build -b html docs docs/_build + +The HTML documentation will be created in the ``docs/_build`` folder. + +.. warning:: + One of the main goals of Sanic is speed. Code that lowers the + performance of Sanic without significant gains in usability, security, + or features may not be merged. Please don’t let this intimidate you! If + you have any concerns about an idea, open an issue for discussion and + help. + +.. _sphinx: http://www.sphinx-doc.org/en/1.5.1/ \ No newline at end of file diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index 12b29a2b..00000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,13 +0,0 @@ -aiofiles -aiohttp>=2.3.0,<=3.2.1 -chardet<=2.3.0 -beautifulsoup4 -coverage -httptools>=0.0.10 -flake8 -pytest==3.3.2 -tox -ujson; sys_platform != "win32" and implementation_name == "cpython" -uvloop; sys_platform != "win32" and implementation_name == "cpython" -gunicorn -multidict>=4.0,<5.0 diff --git a/requirements-docs.txt b/requirements-docs.txt deleted file mode 100644 index e12c1846..00000000 --- a/requirements-docs.txt +++ /dev/null @@ -1,4 +0,0 @@ -sphinx -sphinx_rtd_theme -recommonmark -sphinxcontrib-asyncio diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 3e577b2b..00000000 --- a/requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ -aiofiles -httptools>=0.0.10 -ujson; sys_platform != "win32" and implementation_name == "cpython" -uvloop; sys_platform != "win32" and implementation_name == "cpython" -websockets>=6.0,<7.0 -multidict>=4.0,<5.0 diff --git a/setup.py b/setup.py index 311a91ad..5e8933e5 100644 --- a/setup.py +++ b/setup.py @@ -12,83 +12,90 @@ from setuptools.command.test import test as TestCommand class PyTest(TestCommand): - user_options = [('pytest-args=', 'a', "Arguments to pass to pytest")] + """ + Provide a Test runner to be used from setup.py to run unit tests + """ + + user_options = [("pytest-args=", "a", "Arguments to pass to pytest")] def initialize_options(self): TestCommand.initialize_options(self) - self.pytest_args = '' + self.pytest_args = "" def run_tests(self): import shlex import pytest + errno = pytest.main(shlex.split(self.pytest_args)) sys.exit(errno) -def open_local(paths, mode='r', encoding='utf8'): - path = os.path.join( - os.path.abspath(os.path.dirname(__file__)), - *paths - ) +def open_local(paths, mode="r", encoding="utf8"): + path = os.path.join(os.path.abspath(os.path.dirname(__file__)), *paths) return codecs.open(path, mode, encoding) -with open_local(['sanic', '__init__.py'], encoding='latin1') as fp: +with open_local(["sanic", "__init__.py"], encoding="latin1") as fp: try: - version = re.findall(r"^__version__ = \"([^']+)\"\r?$", - fp.read(), re.M)[0] + version = re.findall( + r"^__version__ = \"([^']+)\"\r?$", fp.read(), re.M + )[0] except IndexError: - raise RuntimeError('Unable to determine version.') + raise RuntimeError("Unable to determine version.") -with open_local(['README.rst']) as rm: +with open_local(["README.rst"]) as rm: long_description = rm.read() setup_kwargs = { - 'name': 'sanic', - 'version': version, - 'url': 'http://github.com/channelcat/sanic/', - 'license': 'MIT', - 'author': 'Channel Cat', - 'author_email': 'channelcat@gmail.com', - 'description': ( - 'A microframework based on uvloop, httptools, and learnings of flask'), - 'long_description': long_description, - 'packages': ['sanic'], - 'platforms': 'any', - 'classifiers': [ - 'Development Status :: 4 - Beta', - 'Environment :: Web Environment', - 'License :: OSI Approved :: MIT License', - 'Programming Language :: Python :: 3.5', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', + "name": "sanic", + "version": version, + "url": "http://github.com/channelcat/sanic/", + "license": "MIT", + "author": "Channel Cat", + "author_email": "channelcat@gmail.com", + "description": ( + "A microframework based on uvloop, httptools, and learnings of flask" + ), + "long_description": long_description, + "packages": ["sanic"], + "platforms": "any", + "classifiers": [ + "Development Status :: 4 - Beta", + "Environment :: Web Environment", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3.5", + "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", ], } -env_dependency = '; sys_platform != "win32" and implementation_name == "cpython"' -ujson = 'ujson>=1.35' + env_dependency -uvloop = 'uvloop>=0.5.3' + env_dependency +env_dependency = ( + '; sys_platform != "win32" ' 'and implementation_name == "cpython"' +) +ujson = "ujson>=1.35" + env_dependency +uvloop = "uvloop>=0.5.3" + env_dependency requirements = [ - 'httptools>=0.0.10', + "httptools>=0.0.10", uvloop, ujson, - 'aiofiles>=0.3.0', - 'websockets>=6.0,<7.0', - 'multidict>=4.0,<5.0', + "aiofiles>=0.3.0", + "websockets>=6.0,<7.0", + "multidict>=4.0,<5.0", ] + tests_require = [ - 'pytest==3.3.2', - 'multidict>=4.0,<5.0', - 'gunicorn', - 'pytest-cov', - 'aiohttp>=2.3.0,<=3.2.1', - 'beautifulsoup4', + "pytest==3.3.2", + "multidict>=4.0,<5.0", + "gunicorn", + "pytest-cov", + "aiohttp>=2.3.0,<=3.2.1", + "beautifulsoup4", uvloop, ujson, - 'pytest-sanic', - 'pytest-sugar' + "pytest-sanic", + "pytest-sugar", ] if strtobool(os.environ.get("SANIC_NO_UJSON", "no")): @@ -102,9 +109,21 @@ if strtobool(os.environ.get("SANIC_NO_UVLOOP", "no")): requirements.remove(uvloop) tests_require.remove(uvloop) -setup_kwargs['install_requires'] = requirements -setup_kwargs['tests_require'] = tests_require -setup_kwargs['cmdclass'] = { - 'test': PyTest +extras_require = { + "test": tests_require, + "dev": tests_require + ["aiofiles", "tox", "black", "flake8"], + "docs": [ + "sphinx", + "sphinx_rtd_theme", + "recommonmark", + "sphinxcontrib-asyncio", + "docutils", + "pygments" + ], } + +setup_kwargs["install_requires"] = requirements +setup_kwargs["tests_require"] = tests_require +setup_kwargs["extras_require"] = extras_require +setup_kwargs["cmdclass"] = {"test": PyTest} setup(**setup_kwargs)