Skip to content

Commit be75b82

Browse files
FlorianHockmannFlorianHockmann
authored
Merge pull request #41 from pm-osc/jg1-initial-pr
initial version of JanusGraph-Python supporting JanusGraph 1.0
2 parents e546fac + ff2168d commit be75b82

34 files changed

Lines changed: 1502 additions & 10 deletions

‎.github/workflows/python.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Copyright 2024 JanusGraph Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
name: janusgraph-python
16+
17+
on:
18+
push:
19+
branches: "**"
20+
pull_request:
21+
branches: "**"
22+
23+
permissions:
24+
contents: read
25+
26+
jobs:
27+
build:
28+
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- uses: actions/checkout@v3
33+
- name: Set up Python 3.9
34+
uses: actions/setup-python@v3
35+
with:
36+
python-version: "3.9"
37+
- name: Install dependencies
38+
run: |
39+
python -m pip install --upgrade pip
40+
pip install -r requirements.txt
41+
pip install -r tests/requirements.txt
42+
- name: Test with pytest
43+
run: |
44+
python -m pytest

‎.gitignore‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# poetry
98+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
99+
# This is especially recommended for binary packages to ensure reproducibility, and is more
100+
# commonly ignored for libraries.
101+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
102+
#poetry.lock
103+
104+
# pdm
105+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
106+
#pdm.lock
107+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
108+
# in version control.
109+
# https://pdm.fming.dev/#use-with-ide
110+
.pdm.toml
111+
112+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
113+
__pypackages__/
114+
115+
# Celery stuff
116+
celerybeat-schedule
117+
celerybeat.pid
118+
119+
# SageMath parsed files
120+
*.sage.py
121+
122+
# Environments
123+
.env
124+
.venv
125+
env/
126+
venv/
127+
ENV/
128+
env.bak/
129+
venv.bak/
130+
131+
# Spyder project settings
132+
.spyderproject
133+
.spyproject
134+
135+
# Rope project settings
136+
.ropeproject
137+
138+
# mkdocs documentation
139+
/site
140+
141+
# mypy
142+
.mypy_cache/
143+
.dmypy.json
144+
dmypy.json
145+
146+
# Pyre type checker
147+
.pyre/
148+
149+
# pytype static type analyzer
150+
.pytype/
151+
152+
# Cython debug symbols
153+
cython_debug/
154+
155+
# PyCharm
156+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
157+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158+
# and can be added to the global gitignore or merged into this file. For a more nuclear
159+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
160+
#.idea/
161+
162+
163+
.DS_Store
164+
.coverage

‎APACHE-2.0.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@
187187
same "printed page" as the copyright notice for easier
188188
identification within third-party archives.
189189

190-
Copyright [yyyy] [name of copyright owner]
190+
Copyright 2024 JanusGraph-Python Authors
191191

192192
Licensed under the Apache License, Version 2.0 (the "License");
193193
you may not use this file except in compliance with the License.
@@ -199,4 +199,4 @@
199199
distributed under the License is distributed on an "AS IS" BASIS,
200200
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201201
See the License for the specific language governing permissions and
202-
limitations under the License.
202+
limitations under the License.

‎BUILDING.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Building JanusGraph-Python
2+
3+
## Requirements
4+
5+
* [Python 3.9][python39] or newer is needed to run the project.
6+
* [Docker][docker] needs to be running in order to execute the integration tests as they automatically start a JanusGraph Docker container.
7+
* [pytest][pytest] and [testcontainers][testcontainers] are needed to test the project.
8+
9+
## Test
10+
11+
The library can be tested by executing:
12+
13+
```sh
14+
pip install -r requirements.txt
15+
pip install -r tests/requirements.txt
16+
17+
python -m pytest
18+
```
19+
20+
The library can be packed into PyPI package by executing:
21+
22+
```sh
23+
pip install build
24+
25+
python -m build
26+
```
27+
28+
[python39]: https://www.python.org/downloads/release/python-390/
29+
[docker]: https://www.docker.com/
30+
[pytest]: https://docs.pytest.org/
31+
[testcontainers]: https://pypi.org/project/testcontainers/

‎README.md‎

Lines changed: 116 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,116 @@
1-
# JanusGraph Python driver
2-
3-
## License
4-
5-
JanusGraph Python driver code is provided under the [Apache 2.0
6-
license](APACHE-2.0.txt) and documentation is provided under the [CC-BY-4.0
7-
license](CC-BY-4.0.txt). For details about this dual-license structure, please
8-
see [`LICENSE.txt`](LICENSE.txt).
1+
# JanusGraph-Python
2+
3+
JanusGraph-Python extends Apache TinkerPop™'s [Gremlin-Python][gremlinpython] with
4+
support for [JanusGraph][janusgraph]-specific types.
5+
6+
## Usage
7+
8+
To connect to JanusGraph Server, a `DriverRemoteConnection` instance needs to be
9+
created and configured with a message serializer that adds support for
10+
JanusGraph specific types.
11+
12+
This can be done like this for GraphSON 3:
13+
14+
```python
15+
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
16+
from janusgraph_python.driver.serializer import JanusGraphSONSerializersV3d0
17+
18+
connection = DriverRemoteConnection(
19+
'ws://localhost:8182/gremlin', 'g',
20+
message_serializer=JanusGraphSONSerializersV3d0())
21+
```
22+
23+
Note that the client should be disposed on shut down to release resources and
24+
to close open connections with `connection.close()`.
25+
The connection can then be used to configure a `GraphTraversalSource`:
26+
27+
```python
28+
from gremlin_python.process.anonymous_traversal import traversal
29+
30+
g = traversal().with_remote(connection)
31+
# Reuse 'g' across the application
32+
```
33+
34+
The `GraphTraversalSource` `g` can now be used to spawn Gremlin traversals:
35+
36+
```python
37+
hercules_age = g.V().has("demigod", "name", "hercules").values("age").next()
38+
print(f"Hercules is {hercules_age} years old.")
39+
```
40+
41+
Refer to the chapter [Gremlin Query Language][gremlin-chapter] in the
42+
JanusGraph docs for an introduction to Gremlin and pointers to further
43+
resources.
44+
The main syntactical difference for Gremlin-Python is that it follows Python naming
45+
conventions, e.g., method names use snake_case instead of camelCase. Other difference is that when Python reserved words (e.g. "is") overlap with Gremlin steps or tokens, those gets underscore suffix (e.g. "is_").
46+
47+
### Text Predicates
48+
49+
The `Text` class provides methods for
50+
[full-text and string searches][text-predicates]:
51+
52+
```python
53+
from janusgraph_python.process.traversal import Text
54+
55+
g.V().has("demigod", "name", Text.text_prefix("herc")).to_list()
56+
```
57+
58+
The other text predicates can be used the same way.
59+
60+
## Version Compatibility
61+
62+
The lowest supported JanusGraph version is 1.0.0.
63+
The following table shows the supported JanusGraph versions for each version
64+
of JanusGraph-Python:
65+
66+
| JanusGraph-Python | JanusGraph |
67+
| ----------------- | ---------------------- |
68+
| 1.0.z | 1.0.z |
69+
70+
While it should also be possible to use JanusGraph-Python with other versions of
71+
JanusGraph than mentioned here, compatibility is not tested and some
72+
functionality (like added Gremlin steps) will not work as it is not supported
73+
yet in case of an older JanusGraph version or was removed in a newer JanusGraph
74+
version.
75+
76+
## Serialization Formats
77+
78+
JanusGraph-Python supports GraphSON 3 only. GraphBinary is not yet
79+
supported.
80+
81+
Not all of the JanusGraph-specific types are already supported by the formats:
82+
83+
| Format | RelationIdentifier | Text predicates | Geoshapes | Geo predicates |
84+
| ----------- | ------------------ | --------------- | --------- | -------------- |
85+
| GraphSON3 | x | x | - | - |
86+
| GraphBinary | - | - | - | - |
87+
88+
## Community
89+
90+
JanusGraph-Python uses the same communication channels as JanusGraph in general.
91+
So, please refer to the
92+
[_Community_ section in JanusGraph's main repository][janusgraph-community]
93+
for more information about these various channels.
94+
95+
Please use GitHub issues only to report bugs or request features.
96+
97+
## Contributing
98+
99+
Please see
100+
[`CONTRIBUTING.md` in JanusGraph's main repository][janusgraph-contributing]
101+
for more information, including CLAs and best practices for working with
102+
GitHub.
103+
104+
## License
105+
106+
JanusGraph-Python code is provided under the [Apache 2.0 license](APACHE-2.0.txt)
107+
and documentation is provided under the [CC-BY-4.0 license](CC-BY-4.0.txt). For
108+
details about this dual-license structure, please see
109+
[`LICENSE.txt`](LICENSE.txt).
110+
111+
[janusgraph]: https://janusgraph.org/
112+
[gremlinpython]: https://tinkerpop.apache.org/docs/current/reference/#gremlin-python
113+
[gremlin-chapter]: https://docs.janusgraph.org/getting-started/gremlin/
114+
[text-predicates]: https://docs.janusgraph.org/interactions/search-predicates/#text-predicate
115+
[janusgraph-community]: https://github.com/JanusGraph/janusgraph#community
116+
[janusgraph-contributing]: https://github.com/JanusGraph/janusgraph/blob/master/CONTRIBUTING.md

‎janusgraph_python/__init__.py‎

Whitespace-only changes.

‎janusgraph_python/driver/__init__.py‎

Whitespace-only changes.

0 commit comments

Comments
 (0)