Skip to content

Commit 8bb37e2

Browse files
blink1073blink1073
authored
ARROW-194 Convert top level docs to Markdown (#181)
* ARROW-194 Convert top level docs to Markdown * add md files * formatting * remove top section of readme
1 parent be1ddcf commit 8bb37e2

File tree

6 files changed

+146
-147
lines changed

6 files changed

+146
-147
lines changed

‎bindings/python/MANIFEST.in

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
include README.rst
1+
include README.md
22
include LICENSE
33
include *.sh
44
include pyproject.toml
@@ -7,8 +7,7 @@ exclude THIRD-PARTY-NOTICES
77
exclude addtags.py
88
exclude benchmark.py
99
exclude repair_wheel.py
10-
exclude .flake8
11-
exclude RELEASE.rst
10+
exclude RELEASE.md
1211
exclude asv.conf.json
1312

1413
graft pymongoarrow

‎bindings/python/README.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# PyMongoArrow
2+
3+
**PyMongoArrow** is a companion library to PyMongo that contains tools
4+
for loading MongoDB query result sets as Apache Arrow tables, Pandas
5+
DataFrames or NumPy arrays.
6+
7+
```pycon
8+
>>> from pymongoarrow.monkey import patch_all
9+
... patch_all()
10+
... from pymongoarrow.api import Schema
11+
... schema = Schema({"_id": int, "qty": float})
12+
... from pymongo import MongoClient
13+
... client = MongoClient()
14+
... client.db.data.insert_many(
15+
... [{"_id": 1, "qty": 25.4}, {"_id": 2, "qty": 16.9}, {"_id": 3, "qty": 2.3}]
16+
... )
17+
... data_frame = client.db.test.find_pandas_all({}, schema=schema)
18+
... data_frame
19+
_id qty
20+
0 1 25.4
21+
1 2 16.9
22+
2 3 2.3
23+
... arrow_table = client.db.test.find_arrow_all({}, schema=schema)
24+
# The schema may also be omitted
25+
... arrow_table = client.db.test.find_arrow_all({})
26+
... arrow_table
27+
pyarrow.Table
28+
_id: int64
29+
qty: double
30+
... ndarrays = client.db.test.find_numpy_all({}, schema=schema)
31+
... ndarrays
32+
{'_id': array([1, 2, 3]), 'qty': array([25.4, 16.9, 2.3])}
33+
```
34+
35+
**PyMongoArrow** is the recommended way to materialize MongoDB query
36+
result sets as contiguous-in-memory, typed arrays suited for in-memory
37+
analytical processing applications.
38+
39+
## Installing PyMongoArrow
40+
41+
PyMongoArrow is available on PyPI:
42+
43+
```bash
44+
python -m pip install pymongoarrow
45+
```
46+
47+
To use PyMongoArrow with MongoDB Atlas' `mongodb+srv://` URIs, you will
48+
need to also install PyMongo with the `srv` extra:
49+
50+
```bash
51+
python -m pip install 'pymongo[srv]' pymongoarrow
52+
```
53+
54+
To use PyMongoArrow APIs that return query result sets as pandas
55+
DataFrame instances, you will also need to have the `pandas` package
56+
installed:
57+
58+
```bash
59+
python -m pip install pandas
60+
```
61+
62+
Note: `pymongoarrow` is not supported or tested on big-endian systems
63+
(e.g. Linux s390x).
64+
65+
## Development Install
66+
67+
See the instructions on [Read the
68+
Docs](https://mongo-arrow.readthedocs.io/en/latest).
69+
70+
## Documentation
71+
72+
Full documentation is available on [Read the
73+
Docs](https://mongo-arrow.readthedocs.io/en/latest).

‎bindings/python/README.rst

Lines changed: 0 additions & 77 deletions
This file was deleted.

‎bindings/python/RELEASE.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# PyMongoArrow Releases
2+
3+
## Versioning
4+
5+
PyMongoArrow's version numbers follow [semantic
6+
versioning](http://semver.org/): each version number is structured
7+
"major.minor.patch". Patch releases fix bugs, minor releases add
8+
features (and may fix bugs), and major releases include API changes that
9+
break backwards compatibility (and may add features and fix bugs).
10+
11+
In between releases we add .devN to the version number to denote the
12+
version under development. So if we just released 2.3.0, then the
13+
current dev version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the
14+
next release we replace all instances of 2.x.x.devN in the docs with the
15+
new version number.
16+
17+
<https://www.python.org/dev/peps/pep-0440/>
18+
19+
## Release Process
20+
21+
1. Ensure that the latest commit is passing CI on GitHub Actions as
22+
expected.
23+
24+
2. Check JIRA to ensure all the tickets in this version have been
25+
completed.
26+
27+
3. Add release notes to `doc/source/changelog.rst`. Generally just
28+
summarize/clarify the git log, but you might add some more long form
29+
notes for big changes.
30+
31+
4. Replace the `devN` version number w/ the new version number (see
32+
note above in [Versioning](#versioning)). Make sure version number
33+
is updated in `pymongoarrow/version.py`. Commit the change and tag
34+
the release. Immediately bump the version number to `dev0` in a new
35+
commit:
36+
37+
$ # Bump to release version number
38+
$ git commit -a -m "BUMP <release version number>"
39+
$ git tag -a "<release version number>" -m "BUMP <release version number>"
40+
$ # Bump to dev version number
41+
$ git commit -a -m "BUMP <dev version number>"
42+
$ git push
43+
$ git push --tags
44+
45+
5. Pushing a tag will trigger the release process on GitHub Actions
46+
that will require a member of the team to authorize the deployment.
47+
Navigate to
48+
<https://github.com/mongodb-labs/mongo-arrow/actions/workflows/release-python.yml>
49+
and wait for the publish to complete.
50+
51+
6. Make sure the new version appears on
52+
<https://mongo-arrow.readthedocs.io/en/stable/>. If the new version
53+
does not show up automatically, trigger a rebuild of "latest":
54+
<https://readthedocs.org/projects/mongo-arrow/builds/>
55+
56+
7. Publish the release version in Jira.
57+
58+
8. Announce the release on:
59+
<https://www.mongodb.com/community/forums/c/announcements/driver-releases>
60+
61+
9. Create a GitHub Release for the tag using
62+
<https://github.com/mongodb/mongo-arrow/releases/new>. The title
63+
should be "PyMongoArrow X.Y.Z", and the description should contain a
64+
link to the release notes on the the community forum, e.g. "Release
65+
notes:
66+
mongodb.com/community/forums/t/pymongoarrow-0-1-1-released/104574."
67+
68+
10. Wait for automated update PR on conda-forge, e.g.:
69+
<https://github.com/conda-forge/pymongoarrow-feedstock/pull/24>
70+
Update dependencies if needed.

‎bindings/python/RELEASE.rst

Lines changed: 0 additions & 63 deletions
This file was deleted.

‎bindings/python/pyproject.toml

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ classifiers = [
3030
"Programming Language :: Python :: Implementation :: CPython",
3131
"Topic :: Database",
3232
]
33+
readme = "README.md"
3334
requires-python = ">=3.8"
3435
dependencies = [
3536
# Must be kept in sync with "build_sytem.requires" above.
@@ -40,10 +41,6 @@ dependencies = [
4041
]
4142
dynamic = ["version"]
4243

43-
[project.readme]
44-
file = "README.rst"
45-
content-type = "text/x-rst"
46-
4744
[project.urls]
4845
Homepage = "https://github.com/mongodb-labs/mongo-arrow/tree/main/bindings/python"
4946

0 commit comments

Comments
 (0)