diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4a13a776 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to Motor + +Contributions are encouraged. Please read these guidelines before +sending a pull request. + +## Bugfixes and New Features + +Before starting to write code, look for existing tickets or create one +in [Jira](https://jira.mongodb.org/browse/MOTOR) for your specific issue +or feature request. + +## Running Tests + +Install a recent version of MongoDB and run it on the default port from +a clean data directory. Pass "--setParameter enableTestCommands=1" to +mongod to enable testing MotorCursor's `max_time_ms` method. + +Control how the tests connect to MongoDB with these environment +variables: + +- `DB_IP`: Defaults to "localhost", can be a domain name or IP +- `DB_PORT`: Defaults to 27017 +- `DB_USER`, `DB_PASSWORD`: To test with authentication, create an + admin user and set these environment variables to the username and + password +- `CERT_DIR`: Path with alternate client.pem and ca.pem for testing. + Otherwise the suite uses those in test/certificates/. + +Install [tox](https://testrun.org/tox/) and run it from the command line +in the repository directory. You will need a variety of Python +interpreters installed. For a minimal test, ensure you have your desired +Python version on your path, and run: + +```bash +tox -m test +``` + +The doctests pass with Python 3.7+ and a MongoDB 5.0 instance running on +port 27017: + +```bash +tox -m doctest +``` + +## Running Linters + +Motor uses [pre-commit](https://pypi.org/project/pre-commit/) for +managing linting of the codebase. `pre-commit` performs various checks +on all files in Motor and uses tools that help follow a consistent code +style within the codebase. + +To set up `pre-commit` locally, run: + +```bash +pip install pre-commit # or brew install pre-commit for global install. +pre-commit install +``` +To run `pre-commit` manually, run: + +```bash +tox -m lint +``` + +## General Guidelines + +- Avoid backward breaking changes if at all possible. +- Write inline documentation for new classes and methods. +- Add yourself to doc/contributors.rst :) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 10c7b675..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,65 +0,0 @@ -Contributing to Motor -===================== - -Contributions are encouraged. Please read these guidelines before sending a -pull request. - -Bugfixes and New Features -------------------------- - -Before starting to write code, look for existing tickets or create one in `Jira -`_ for your specific issue or feature -request. - -Running Tests -------------- - -Install a recent version of MongoDB and run it on the default port from a clean -data directory. Pass "--setParameter enableTestCommands=1" to mongod to enable -testing MotorCursor's ``max_time_ms`` method. - -Control how the tests connect to MongoDB with these environment variables: - - - ``DB_IP``: Defaults to "localhost", can be a domain name or IP - - ``DB_PORT``: Defaults to 27017 - - ``DB_USER``, ``DB_PASSWORD``: To test with authentication, create an admin - user and set these environment variables to the username and password - - ``CERT_DIR``: Path with alternate client.pem and ca.pem for testing. - Otherwise the suite uses those in test/certificates/. - -Install `tox`_ and run it from the command line in the repository directory. -You will need a variety of Python interpreters installed. For a minimal test, -ensure you have your desired Python version on your path, and run:: - - > tox -m test - -The doctests pass with Python 3.7+ and a MongoDB 5.0 instance running on -port 27017: - - > tox -m doctest - -.. _tox: https://testrun.org/tox/ - -Running Linters ---------------- - -Motor uses `pre-commit `_ -for managing linting of the codebase. -``pre-commit`` performs various checks on all files in Motor and uses tools -that help follow a consistent code style within the codebase. - -To set up ``pre-commit`` locally, run:: - - pip install pre-commit - pre-commit install - -To run ``pre-commit`` manually, run:: - - > tox -m lint - -General Guidelines ------------------- - -- Avoid backward breaking changes if at all possible. -- Write inline documentation for new classes and methods. -- Add yourself to doc/contributors.rst :) diff --git a/MANIFEST.in b/MANIFEST.in index 8e33630e..5eb26eb7 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include README.rst +include README.md include LICENSE include tox.ini include pyproject.toml @@ -19,11 +19,10 @@ recursive-include motor *.pyi recursive-include motor *.typed recursive-include motor *.py -exclude .flake8 exclude .readthedocs.yaml exclude .git-blame-ignore-revs exclude .pre-commit-config.yaml exclude release.sh -exclude RELEASE.rst -exclude CONTRIBUTING.rst +exclude RELEASE.md +exclude CONTRIBUTING.md exclude .evergreen/* diff --git a/README.md b/README.md new file mode 100644 index 00000000..72a37480 --- /dev/null +++ b/README.md @@ -0,0 +1,205 @@ +# Motor + +![image](https://raw.github.com/mongodb/motor/master/doc/_static/motor.png) + +- Info: Motor is a full-featured, non-blocking [MongoDB](http://mongodb.org/) +driver for Python [Tornado](http://tornadoweb.org/) and +[asyncio](https://docs.python.org/3/library/asyncio.html) applications. + +- Documentation: Available at +[motor.readthedocs.io](https://motor.readthedocs.io/en/stable/) + +- Author: A. Jesse Jiryu Davis + +## About + +Motor presents a coroutine-based API for non-blocking access to MongoDB. +The source is [on GitHub](https://github.com/mongodb/motor) and the docs +are on [ReadTheDocs](https://motor.readthedocs.io/en/stable/). + +> "We use Motor in high throughput environments, processing tens of +> thousands of requests per second. It allows us to take full advantage +> of modern hardware, ensuring we utilise the entire capacity of our +> purchased CPUs. This helps us be more efficient with computing power, +> compute spend and minimises the environmental impact of our +> infrastructure as a result." +> +> --*David Mytton, Server Density* +> +> "We develop easy-to-use sensors and sensor systems with open source +> software to ensure every innovator, from school child to laboratory +> researcher, has the same opportunity to create. We integrate Motor +> into our software to guarantee massively scalable sensor systems for +> everyone." +> +> --*Ryan Smith, inXus Interactive* + +## Support / Feedback + +For issues with, questions about, or feedback for PyMongo, please look +into our [support channels](https://support.mongodb.com/welcome). Please +do not email any of the Motor developers directly with issues or +questions - you're more likely to get an answer on the +[StackOverflow](https://stackoverflow.com/questions/tagged/mongodb) +(using a "mongodb" tag). + +## Bugs / Feature Requests + +Think you've found a bug? Want to see a new feature in Motor? Please +open a case in our issue management tool, JIRA: + +- [Create an account and login](https://jira.mongodb.org). +- Navigate to [the MOTOR + project](https://jira.mongodb.org/browse/MOTOR). +- Click **Create Issue** - Please provide as much information as + possible about the issue type and how to reproduce it. + +Bug reports in JIRA for all driver projects (i.e. MOTOR, CSHARP, JAVA) +and the Core Server (i.e. SERVER) project are **public**. + +### How To Ask For Help + +Please include all of the following information when opening an issue: + +- Detailed steps to reproduce the problem, including full traceback, if + possible. + +- The exact python version used, with patch level: + +```bash +python -c "import sys; print(sys.version)" +``` + +- The exact version of Motor used, with patch level: + +```bash +python -c "import motor; print(motor.version)" +``` + +- The exact version of PyMongo used, with patch level: + +```bash +python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())" +``` + +- The exact Tornado version, if you are using Tornado: + +```bash +python -c "import tornado; print(tornado.version)" +``` + +- The operating system and version (e.g. RedHat Enterprise Linux 6.4, + OSX 10.9.5, ...) + +### Security Vulnerabilities + +If you've identified a security vulnerability in a driver or any other +MongoDB project, please report it according to the [instructions +here](https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). + +## Installation + +Motor can be installed with [pip](http://pypi.python.org/pypi/pip): + +```bash +pip install motor +``` + +## Dependencies + +Motor works in all the environments officially supported by Tornado or +by asyncio. It requires: + +- Unix (including macOS) or Windows. +- [PyMongo](http://pypi.python.org/pypi/pymongo/) >=4.1,<5 +- Python 3.7+ + +Optional dependencies: + +Motor supports same optional dependencies as PyMongo. Required +dependencies can be installed along with Motor. + +GSSAPI authentication requires `gssapi` extra dependency. The correct +dependency can be installed automatically along with Motor: + +```bash +pip install "motor[gssapi]" +``` + +similarly, + +MONGODB-AWS authentication requires `aws` extra dependency: + +```bash +pip install "motor[aws]" +``` + +Support for mongodb+srv:// URIs requires `srv` extra dependency: + +```bash +pip install "motor[srv]" +``` + +OCSP requires `ocsp` extra dependency: + +```bash +pip install "motor[ocsp]" +``` + +Wire protocol compression with snappy requires `snappy` extra +dependency: + +```bash +pip install "motor[snappy]" +``` + +Wire protocol compression with zstandard requires `zstd` extra +dependency: + +```bash +pip install "motor[zstd]" +``` + +Client-Side Field Level Encryption requires `encryption` extra +dependency: + +```bash +pip install "motor[encryption]" +``` + +You can install all dependencies automatically with the following +command: + +```bash +pip install "motor[gssapi,aws,ocsp,snappy,srv,zstd,encryption]" +``` + +See +[requirements](https://motor.readthedocs.io/en/stable/requirements.html) +for details about compatibility. + +## Examples + +See the [examples on +ReadTheDocs](https://motor.readthedocs.io/en/stable/examples/index.html). + +## Documentation + +Motor's documentation is on +[ReadTheDocs](https://motor.readthedocs.io/en/stable/). + +Build the documentation with Python 3.7+. Install +[sphinx](http://sphinx.pocoo.org/), [Tornado](http://tornadoweb.org/), +and [aiohttp](https://github.com/aio-libs/aiohttp), and do +`cd doc; make html`. + +## Learning Resources + +- MongoDB Learn - [Python +courses](https://learn.mongodb.com/catalog?labels=%5B%22Language%22%5D&values=%5B%22Python%22%5D). +- [Python Articles on Developer +Center](https://www.mongodb.com/developer/languages/python/). + +## Testing + +Run `python setup.py test`. Tests are located in the `test/` directory. diff --git a/README.rst b/README.rst deleted file mode 100644 index b8ebe3bf..00000000 --- a/README.rst +++ /dev/null @@ -1,184 +0,0 @@ -===== -Motor -===== - -.. image:: https://raw.github.com/mongodb/motor/master/doc/_static/motor.png - -:Info: Motor is a full-featured, non-blocking MongoDB_ driver for Python - Tornado_ and asyncio_ applications. -:Documentation: Available at `motor.readthedocs.io `_ -:Author: A\. Jesse Jiryu Davis - -About -===== - -Motor presents a coroutine-based API for non-blocking access -to MongoDB. The source is `on GitHub `_ -and the docs are on ReadTheDocs_. - - "We use Motor in high throughput environments, processing tens of thousands - of requests per second. It allows us to take full advantage of modern - hardware, ensuring we utilise the entire capacity of our purchased CPUs. - This helps us be more efficient with computing power, compute spend and - minimises the environmental impact of our infrastructure as a result." - - --*David Mytton, Server Density* - - "We develop easy-to-use sensors and sensor systems with open source - software to ensure every innovator, from school child to laboratory - researcher, has the same opportunity to create. We integrate Motor into our - software to guarantee massively scalable sensor systems for everyone." - - --*Ryan Smith, inXus Interactive* - -Support / Feedback -================== - -For issues with, questions about, or feedback for PyMongo, please look into -our `support channels `_. Please -do not email any of the Motor developers directly with issues or -questions - you're more likely to get an answer on the `StackOverflow `_ (using a "mongodb" tag). - -Bugs / Feature Requests -======================= - -Think you've found a bug? Want to see a new feature in Motor? Please open a -case in our issue management tool, JIRA: - -- `Create an account and login `_. -- Navigate to `the MOTOR project `_. -- Click **Create Issue** - Please provide as much information as possible about the issue type and how to reproduce it. - -Bug reports in JIRA for all driver projects (i.e. MOTOR, CSHARP, JAVA) and the -Core Server (i.e. SERVER) project are **public**. - -How To Ask For Help -------------------- - -Please include all of the following information when opening an issue: - -- Detailed steps to reproduce the problem, including full traceback, if possible. -- The exact python version used, with patch level:: - - $ python -c "import sys; print(sys.version)" - -- The exact version of Motor used, with patch level:: - - $ python -c "import motor; print(motor.version)" - -- The exact version of PyMongo used, with patch level:: - - $ python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())" - -- The exact Tornado version, if you are using Tornado:: - - $ python -c "import tornado; print(tornado.version)" - -- The operating system and version (e.g. RedHat Enterprise Linux 6.4, OSX 10.9.5, ...) - -Security Vulnerabilities ------------------------- - -If you've identified a security vulnerability in a driver or any other -MongoDB project, please report it according to the `instructions here -`_. - -Installation -============ - -Motor can be installed with `pip `_:: - - $ pip install motor - -Dependencies -============ - -Motor works in all the environments officially supported by Tornado or by -asyncio. It requires: - -* Unix (including macOS) or Windows. -* PyMongo_ >=4.1,<5 -* Python 3.7+ - -Optional dependencies: - -Motor supports same optional dependencies as PyMongo. Required dependencies can be installed -along with Motor. - -GSSAPI authentication requires ``gssapi`` extra dependency. The correct -dependency can be installed automatically along with Motor:: - - $ pip install "motor[gssapi]" - -similarly, - -MONGODB-AWS authentication requires ``aws`` extra dependency:: - - $ pip install "motor[aws]" - -Support for mongodb+srv:// URIs requires ``srv`` extra dependency:: - - $ pip install "motor[srv]" - -OCSP requires ``ocsp`` extra dependency:: - - $ pip install "motor[ocsp]" - -Wire protocol compression with snappy requires ``snappy`` extra dependency:: - - $ pip install "motor[snappy]" - -Wire protocol compression with zstandard requires ``zstd`` extra dependency:: - - $ pip install "motor[zstd]" - -Client-Side Field Level Encryption requires ``encryption`` extra dependency:: - - $ pip install "motor[encryption]" - -You can install all dependencies automatically with the following -command:: - - $ pip install "motor[gssapi,aws,ocsp,snappy,srv,zstd,encryption]" - -See `requirements `_ -for details about compatibility. - -Examples -======== - -See the `examples on ReadTheDocs `_. - -Documentation -============= - -Motor's documentation is on ReadTheDocs_. - -Build the documentation with Python 3.7+. Install sphinx_, Tornado_, and aiohttp_, -and do ``cd doc; make html``. - -Learning Resources -================== - -MongoDB Learn - `Python courses `_. -`Python Articles on Developer Center `_. - -Testing -======= - -Run ``python setup.py test``. -Tests are located in the ``test/`` directory. - -.. _PyMongo: http://pypi.python.org/pypi/pymongo/ - -.. _MongoDB: http://mongodb.org/ - -.. _Tornado: http://tornadoweb.org/ - -.. _asyncio: https://docs.python.org/3/library/asyncio.html - -.. _aiohttp: https://github.com/aio-libs/aiohttp - -.. _ReadTheDocs: https://motor.readthedocs.io/en/stable/ - -.. _sphinx: http://sphinx.pocoo.org/ diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000..225d07b7 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,71 @@ +# Motor Releases + +## Versioning + +Motor's version numbers follow [semantic +versioning](http://semver.org/): each version number is structured +"major.minor.patch". Patch releases fix bugs, minor releases add +features (and may fix bugs), and major releases include API changes that +break backwards compatibility (and may add features and fix bugs). + +In between releases we add .devN to the version number to denote the +version under development. So if we just released 2.3.0, then the +current dev version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the +next release we replace all instances of 2.x.x.devN in the docs with the +new version number. + + + +## Release Process + +Motor ships a [pure Python +wheel](https://packaging.python.org/guides/distributing-packages-using-setuptools/#pure-python-wheels) +and a [source +distribution](https://packaging.python.org/guides/distributing-packages-using-setuptools/#source-distributions). + +1. Motor is tested on Evergreen. Ensure that the latest commit is + passing CI as expected: + . + +2. Check JIRA to ensure all the tickets in this version have been + completed. + +3. Add release notes to `doc/changelog.rst`. Generally just + summarize/clarify the git log, but you might add some more long form + notes for big changes. + +4. Replace the `devN` version number w/ the new version number (see + note above in [Versioning](#versioning)) in `motor/_version.py`. + Commit the change and tag the release. Immediately bump the version + number to `dev0` in a new commit: + + $ # Bump to release version number + $ git commit -a -m "BUMP " + $ git tag -a "" -m "BUMP " + $ # Bump to dev version number + $ git commit -a -m "BUMP " + $ git push + $ git push --tags + +5. Bump the version number to `.dev0` in + `motor/_version.py`, commit, then push. + +6. Authorize the deployment for the tagged version on the release + GitHub Action and wait for it to successfully publish to PyPI. + +7. Make sure the new version appears on + . If the new version does not show up + automatically, trigger a rebuild of "latest": + + +8. Publish the release version in Jira and add a brief description + about the reason for the release or the main feature. + +9. Announce the release on: + + +10. Create a GitHub Release for the tag using + . The title should be + "Motor X.Y.Z", and the description should contain a link to the + release notes on the the community forum, e.g. "Release notes: + mongodb.com/community/forums/t/motor-2-5-1-released/120313." diff --git a/RELEASE.rst b/RELEASE.rst deleted file mode 100644 index e2772206..00000000 --- a/RELEASE.rst +++ /dev/null @@ -1,67 +0,0 @@ -============== -Motor Releases -============== - -Versioning ----------- - -Motor's version numbers follow `semantic versioning `_: -each version number is structured "major.minor.patch". Patch releases fix -bugs, minor releases add features (and may fix bugs), and major releases -include API changes that break backwards compatibility (and may add features -and fix bugs). - -In between releases we add .devN to the version number to denote the version -under development. So if we just released 2.3.0, then the current dev -version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the next release we -replace all instances of 2.x.x.devN in the docs with the new version number. - -https://www.python.org/dev/peps/pep-0440/ - -Release Process ---------------- - -Motor ships a `pure Python wheel `_ -and a `source distribution `_. - -#. Motor is tested on Evergreen. Ensure that the latest commit is passing CI as - expected: https://evergreen.mongodb.com/waterfall/motor. - -#. Check JIRA to ensure all the tickets in this version have been completed. - -#. Add release notes to ``doc/changelog.rst``. Generally just summarize/clarify - the git log, but you might add some more long form notes for big changes. - -#. Replace the ``devN`` version number w/ the new version number (see - note above in `Versioning`_) in - ``motor/_version.py``. Commit the change and tag the release. - Immediately bump the version number to ``dev0`` in a new commit:: - - $ # Bump to release version number - $ git commit -a -m "BUMP " - $ git tag -a "" -m "BUMP " - $ # Bump to dev version number - $ git commit -a -m "BUMP " - $ git push - $ git push --tags - -#. Bump the version number to ``.dev0`` in ``motor/_version.py``, - commit, then push. - -#. Authorize the deployment for the tagged version on the release GitHub Action and - wait for it to successfully publish to PyPI. - -#. Make sure the new version appears on https://motor.readthedocs.io/. If the - new version does not show up automatically, trigger a rebuild of "latest": - https://readthedocs.org/projects/motor/builds/ - -#. Publish the release version in Jira and add a brief description about the reason - for the release or the main feature. - -#. Announce the release on: - https://www.mongodb.com/community/forums/c/announcements/driver-releases - -#. Create a GitHub Release for the tag using https://github.com/mongodb/motor/releases/new. - The title should be "Motor X.Y.Z", and the description should contain a - link to the release notes on the the community forum, e.g. - "Release notes: mongodb.com/community/forums/t/motor-2-5-1-released/120313." diff --git a/pyproject.toml b/pyproject.toml index c1508f87..dad6a0db 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" name = "motor" dynamic = ["version"] description = "Non-blocking MongoDB driver for Tornado or asyncio" -readme = "README.rst" +readme = "README.md" license = { file = "LICENSE" } requires-python = ">=3.7" authors = [