mongodb/motor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MOTOR-1224 Convert top level docs to Markdown (#244)

Browse Source 
* MOTOR-1224 Convert top level docs to Markdown

* add md files

* fix manifest

* address review
This commit is contained in:
Steven Silvester 2023-12-12 14:12:51 -06:00 committed by GitHub
parent 9a86b616dd
commit 3f8314db62
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 348 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
CONTRIBUTING.md Normal file
View File

@ -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 :)

65
CONTRIBUTING.rst
View File

@ -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
<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`_ 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 <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::
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 :)

7
MANIFEST.in
View File

@ -1,4 +1,4 @@
include README.rst include README.md
include LICENSE include LICENSE
include tox.ini include tox.ini
include pyproject.toml include pyproject.toml
@ -19,11 +19,10 @@ recursive-include motor *.pyi
recursive-include motor *.typed recursive-include motor *.typed
recursive-include motor *.py recursive-include motor *.py
exclude .flake8
exclude .readthedocs.yaml exclude .readthedocs.yaml
exclude .git-blame-ignore-revs exclude .git-blame-ignore-revs
exclude .pre-commit-config.yaml exclude .pre-commit-config.yaml
exclude release.sh exclude release.sh
exclude RELEASE.rst exclude RELEASE.md
exclude CONTRIBUTING.rst exclude CONTRIBUTING.md
exclude .evergreen/* exclude .evergreen/*

205
README.md Normal file
View File

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

184
README.rst
View File

@ -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 <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_.
"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::
$ 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
<https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report>`_.
Installation
============
Motor can be installed with `pip <http://pypi.python.org/pypi/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 <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_.
Build the documentation with Python 3.7+. Install sphinx_, Tornado_, and 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.
.. _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/

71
RELEASE.md Normal file
View File

@ -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.
<https://www.python.org/dev/peps/pep-0440/>
## 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:
<https://evergreen.mongodb.com/waterfall/motor>.
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 <release version number>"
$ git tag -a "<release version number>" -m "BUMP <release version number>"
$ # Bump to dev version number
$ git commit -a -m "BUMP <dev version number>"
$ git push
$ git push --tags
5. Bump the version number to `<next version>.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
<https://motor.readthedocs.io/>. If the new version does not show up
automatically, trigger a rebuild of "latest":
<https://readthedocs.org/projects/motor/builds/>
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:
<https://www.mongodb.com/community/forums/c/announcements/driver-releases>
10. 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."

67
RELEASE.rst
View File

@ -1,67 +0,0 @@
==============
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.
https://www.python.org/dev/peps/pep-0440/
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>`_.
#. 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 <release version number>"
$ git tag -a "<release version number>" -m "BUMP <release version number>"
$ # Bump to dev version number
$ git commit -a -m "BUMP <dev version number>"
$ git push
$ git push --tags
#. Bump the version number to ``<next version>.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."

2
pyproject.toml
View File

@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
name = "motor" name = "motor"
dynamic = ["version"] dynamic = ["version"]
description = "Non-blocking MongoDB driver for Tornado or asyncio" description = "Non-blocking MongoDB driver for Tornado or asyncio"
readme = "README.rst" readme = "README.md"
license = { file = "LICENSE" } license = { file = "LICENSE" }
requires-python = ">=3.7" requires-python = ">=3.7"
authors = [ authors = [