Merge pull request #41 from pm-osc/jg1-initial-pr

initial version of JanusGraph-Python supporting JanusGraph 1.0

.github/workflows/python.yml

@@ -0,0 +1,44 @@
+# Copyright 2024 JanusGraph Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: janusgraph-python
+
+on:
+  push:
+    branches: "**"
+  pull_request:
+    branches: "**"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.9"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install -r tests/requirements.txt
+    - name: Test with pytest
+      run: |
+        python -m pytest

.gitignore

@@ -0,0 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+
+.DS_Store
+.coverage

APACHE-2.0.txt

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2024 JanusGraph-Python Authors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

BUILDING.md

@@ -0,0 +1,31 @@
+# Building JanusGraph-Python
+
+## Requirements
+
+* [Python 3.9][python39] or newer is needed to run the project.
+* [Docker][docker] needs to be running in order to execute the integration tests as they automatically start a JanusGraph Docker container.
+* [pytest][pytest] and [testcontainers][testcontainers] are needed to test the project.
+
+## Test
+
+The library can be tested by executing:
+
+```sh
+pip install -r requirements.txt
+pip install -r tests/requirements.txt
+
+python -m pytest
+```
+
+The library can be packed into PyPI package by executing:
+
+```sh
+pip install build
+
+python -m build
+```
+
+[python39]: https://www.python.org/downloads/release/python-390/
+[docker]: https://www.docker.com/
+[pytest]: https://docs.pytest.org/
+[testcontainers]: https://pypi.org/project/testcontainers/

README.md

@@ -1,8 +1,116 @@
-# JanusGraph Python driver
-
-## License
-
-JanusGraph Python driver code is provided under the [Apache 2.0
-license](APACHE-2.0.txt) and documentation is provided under the [CC-BY-4.0
-license](CC-BY-4.0.txt). For details about this dual-license structure, please
-see [`LICENSE.txt`](LICENSE.txt).
+# JanusGraph-Python
+
+JanusGraph-Python extends Apache TinkerPop™'s [Gremlin-Python][gremlinpython] with
+support for [JanusGraph][janusgraph]-specific types.
+
+## Usage
+
+To connect to JanusGraph Server, a `DriverRemoteConnection` instance needs to be
+created and configured with a message serializer that adds support for
+JanusGraph specific types.
+
+This can be done like this for GraphSON 3:
+
+```python
+from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
+from janusgraph_python.driver.serializer import JanusGraphSONSerializersV3d0
+
+connection = DriverRemoteConnection(
+	'ws://localhost:8182/gremlin', 'g',
+	message_serializer=JanusGraphSONSerializersV3d0())
+```
+
+Note that the client should be disposed on shut down to release resources and
+to close open connections with `connection.close()`.
+The connection can then be used to configure a `GraphTraversalSource`:
+
+```python
+from gremlin_python.process.anonymous_traversal import traversal
+
+g = traversal().with_remote(connection)
+# Reuse 'g' across the application
+```
+
+The `GraphTraversalSource` `g` can now be used to spawn Gremlin traversals:
+
+```python
+hercules_age = g.V().has("demigod", "name", "hercules").values("age").next()
+print(f"Hercules is {hercules_age} years old.")
+```
+
+Refer to the chapter [Gremlin Query Language][gremlin-chapter] in the
+JanusGraph docs for an introduction to Gremlin and pointers to further
+resources.
+The main syntactical difference for Gremlin-Python is that it follows Python naming
+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_").
+
+### Text Predicates
+
+The `Text` class provides methods for
+[full-text and string searches][text-predicates]:
+
+```python
+from janusgraph_python.process.traversal import Text
+
+g.V().has("demigod", "name", Text.text_prefix("herc")).to_list()
+```
+
+The other text predicates can be used the same way.
+
+## Version Compatibility
+
+The lowest supported JanusGraph version is 1.0.0.
+The following table shows the supported JanusGraph versions for each version
+of JanusGraph-Python:
+
+| JanusGraph-Python | JanusGraph             |
+| ----------------- | ---------------------- |
+| 1.0.z             | 1.0.z                  |
+
+While it should also be possible to use JanusGraph-Python with other versions of
+JanusGraph than mentioned here, compatibility is not tested and some
+functionality (like added Gremlin steps) will not work as it is not supported
+yet in case of an older JanusGraph version or was removed in a newer JanusGraph
+version.
+
+## Serialization Formats
+
+JanusGraph-Python supports GraphSON 3 only. GraphBinary is not yet
+supported.
+
+Not all of the JanusGraph-specific types are already supported by the formats:
+
+| Format      | RelationIdentifier | Text predicates | Geoshapes | Geo predicates |
+| ----------- | ------------------ | --------------- | --------- | -------------- |
+| GraphSON3   | x                  | x               | -         | -              |
+| GraphBinary | -                  | -               | -         | -              |
+
+## Community
+
+JanusGraph-Python uses the same communication channels as JanusGraph in general.
+So, please refer to the
+[_Community_ section in JanusGraph's main repository][janusgraph-community]
+for more information about these various channels.
+
+Please use GitHub issues only to report bugs or request features.
+
+## Contributing
+
+Please see
+[`CONTRIBUTING.md` in JanusGraph's main repository][janusgraph-contributing]
+for more information, including CLAs and best practices for working with
+GitHub.
+
+## License
+
+JanusGraph-Python code is provided under the [Apache 2.0 license](APACHE-2.0.txt)
+and documentation is provided under the [CC-BY-4.0 license](CC-BY-4.0.txt). For
+details about this dual-license structure, please see
+[`LICENSE.txt`](LICENSE.txt).
+
+[janusgraph]: https://janusgraph.org/
+[gremlinpython]: https://tinkerpop.apache.org/docs/current/reference/#gremlin-python
+[gremlin-chapter]: https://docs.janusgraph.org/getting-started/gremlin/
+[text-predicates]: https://docs.janusgraph.org/interactions/search-predicates/#text-predicate
+[janusgraph-community]: https://github.com/JanusGraph/janusgraph#community
+[janusgraph-contributing]: https://github.com/JanusGraph/janusgraph/blob/master/CONTRIBUTING.md