Add development container and update READMEs. Add Sphinx furo theme. (#221)

pull/223/head
Edmond Chuc 2 years ago committed by GitHub
parent 4d97f9d171
commit 93107e6bfe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 25
      .devcontainer/Dockerfile
  2. 69
      .devcontainer/devcontainer.json
  3. 2
      .github/workflows/artifacts.yml
  4. 2
      .github/workflows/release.yml
  5. 2
      .github/workflows/tests.yml
  6. 6
      .gitignore
  7. 50
      README.md
  8. 30
      python/README.md
  9. 2
      python/docs/conf.py

@ -0,0 +1,25 @@
# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/rust/.devcontainer/base.Dockerfile
# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): buster, bullseye
ARG VARIANT="bullseye"
FROM mcr.microsoft.com/vscode/devcontainers/rust:0-${VARIANT}
# [Optional] Uncomment this section to install additional packages.
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
&& apt-get -y install --no-install-recommends \
python3 \
python3-venv \
python-is-python3 \
libclang-dev
ENV VIRTUAL_ENV=/opt/venv
RUN python -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
RUN pip install --no-cache-dir \
maturin \
sphinx \
sphinx-autobuild \
furo
# Change owner to the devcontainer user
RUN chown -R 1000:1000 $VIRTUAL_ENV

@ -0,0 +1,69 @@
// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/rust
{
"name": "Rust",
"build": {
"dockerfile": "Dockerfile",
"args": {
// Use the VARIANT arg to pick a Debian OS version: buster, bullseye
// Use bullseye when on local on arm64/Apple Silicon.
"VARIANT": "bullseye"
}
},
"runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"],
// Configure tool-specific properties.
"customizations": {
// Configure properties specific to VS Code.
"vscode": {
// Set *default* container specific settings.json values on container create.
"settings": {
"lldb.executable": "/usr/bin/lldb",
// VS Code don't watch files under ./target
"files.watcherExclude": {
"**/target/**": true
},
"rust-analyzer.checkOnSave.command": "clippy",
"python.defaultInterpreterPath": "/opt/venv/bin/python",
"python.linting.enabled": true,
"python.linting.pylintEnabled": true,
"python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
"python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
"python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
"python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
"python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
"python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
"python.linting.pylintPath": "/opt/venv/bin/pylint",
"python.testing.pytestPath": "/opt/venv/bin/pytest"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"vadimcn.vscode-lldb",
"mutantdino.resourcemonitor",
"rust-lang.rust-analyzer",
"tamasfe.even-better-toml",
"serayuzgur.crates",
"ms-python.python",
"ms-python.vscode-pylance",
"esbenp.prettier-vscode",
"stardog-union.stardog-rdf-grammars"
]
}
},
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [],
// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "git submodule update --init && cargo build",
// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "vscode",
"features": {
"python": "3.10"
}
}

@ -17,7 +17,7 @@ jobs:
with: with:
python-version: 3.8 python-version: 3.8
- run: python -m venv python/venv - run: python -m venv python/venv
- run: source python/venv/bin/activate && pip install --upgrade maturin sphinx - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx furo
- run: source venv/bin/activate && maturin develop - run: source venv/bin/activate && maturin develop
working-directory: ./python working-directory: ./python
- run: source ../venv/bin/activate && sphinx-build -M doctest . build - run: source ../venv/bin/activate && sphinx-build -M doctest . build

@ -184,7 +184,7 @@ jobs:
with: with:
python-version: 3.8 python-version: 3.8
- run: python -m venv python/venv - run: python -m venv python/venv
- run: source python/venv/bin/activate && pip install --upgrade maturin sphinx - run: source python/venv/bin/activate && pip install --upgrade maturin sphinx furo
- run: source venv/bin/activate && maturin develop - run: source venv/bin/activate && maturin develop
working-directory: ./python working-directory: ./python
- run: source ../venv/bin/activate && sphinx-build -M doctest . build - run: source ../venv/bin/activate && sphinx-build -M doctest . build

@ -89,7 +89,7 @@ jobs:
- uses: actions/setup-python@v2 - uses: actions/setup-python@v2
with: with:
python-version: "3.10" python-version: "3.10"
- run: pip install --upgrade maturin sphinx - run: pip install --upgrade maturin sphinx furo
- run: maturin sdist -m python/Cargo.toml - run: maturin sdist -m python/Cargo.toml
- run: pip install target/wheels/*.tar.gz - run: pip install target/wheels/*.tar.gz
- run: python -m unittest - run: python -m unittest

6
.gitignore vendored

@ -8,4 +8,8 @@ lib/tests/rocksdb_bc_data
venv venv
.env .env
data/ data/
.htpasswd .htpasswd
**/docs/_build
**/docs/build
*.so
*.pyc

@ -1,7 +1,6 @@
Oxigraph # Oxigraph
========
[![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) [![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph)
[![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph) [![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph)
[![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/)
[![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph) [![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph)
@ -21,23 +20,32 @@ The development roadmap is using [GitHub milestones](https://github.com/oxigraph
Oxigraph internal design [is described on the wiki](https://github.com/oxigraph/oxigraph/wiki/Architecture). Oxigraph internal design [is described on the wiki](https://github.com/oxigraph/oxigraph/wiki/Architecture).
It is split into multiple parts: It is split into multiple parts:
* [The database written as a Rust library](https://crates.io/crates/oxigraph). Its source code is in the `lib` directory.
[![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph) - [The database written as a Rust library](https://crates.io/crates/oxigraph). Its source code is in the `lib` directory.
[![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph) [![Latest Version](https://img.shields.io/crates/v/oxigraph.svg)](https://crates.io/crates/oxigraph)
* [`pyoxigraph` that exposes Oxigraph to the Python world](https://oxigraph.org/pyoxigraph/). Its source code is in the `python` directory. [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) [![Released API docs](https://docs.rs/oxigraph/badge.svg)](https://docs.rs/oxigraph)
* [JavaScript bindings for Oxigraph](https://www.npmjs.com/package/oxigraph). WebAssembly is used to package Oxigraph into a NodeJS compatible NPM package. Its source code is in the `js` directory. - [`pyoxigraph` that exposes Oxigraph to the Python world](https://oxigraph.org/pyoxigraph/). Its source code is in the `python` directory. [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/)
[![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph) - [JavaScript bindings for Oxigraph](https://www.npmjs.com/package/oxigraph). WebAssembly is used to package Oxigraph into a NodeJS compatible NPM package. Its source code is in the `js` directory.
* [Oxigraph server](https://crates.io/crates/oxigraph_server) that provides a standalone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/) and the [SPARQL 1.1 Graph Store Protocol](https://www.w3.org/TR/sparql11-http-rdf-update/). Its source code is in the `server` directory. [![npm](https://img.shields.io/npm/v/oxigraph)](https://www.npmjs.com/package/oxigraph)
[![Latest Version](https://img.shields.io/crates/v/oxigraph_server.svg)](https://crates.io/crates/oxigraph_server) - [Oxigraph server](https://crates.io/crates/oxigraph_server) that provides a standalone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/) and the [SPARQL 1.1 Graph Store Protocol](https://www.w3.org/TR/sparql11-http-rdf-update/). Its source code is in the `server` directory.
[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/oxigraph/oxigraph?sort=semver)](https://hub.docker.com/r/oxigraph/oxigraph) [![Latest Version](https://img.shields.io/crates/v/oxigraph_server.svg)](https://crates.io/crates/oxigraph_server)
[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/oxigraph/oxigraph?sort=semver)](https://hub.docker.com/r/oxigraph/oxigraph)
Oxigraph implements the following specifications: Oxigraph implements the following specifications:
* [SPARQL 1.1 Query](https://www.w3.org/TR/sparql11-query/), [SPARQL 1.1 Update](https://www.w3.org/TR/sparql11-update/), and [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/).
* [Turtle](https://www.w3.org/TR/turtle/), [TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/), and [RDF XML](https://www.w3.org/TR/rdf-syntax-grammar/) RDF serialization formats for both data ingestion and retrieval using the [Rio library](https://github.com/oxigraph/rio). - [SPARQL 1.1 Query](https://www.w3.org/TR/sparql11-query/), [SPARQL 1.1 Update](https://www.w3.org/TR/sparql11-update/), and [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/).
* [SPARQL Query Results XML Format](http://www.w3.org/TR/rdf-sparql-XMLres/), [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/) and [SPARQL 1.1 Query Results CSV and TSV Formats](https://www.w3.org/TR/sparql11-results-csv-tsv/). - [Turtle](https://www.w3.org/TR/turtle/), [TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/), and [RDF XML](https://www.w3.org/TR/rdf-syntax-grammar/) RDF serialization formats for both data ingestion and retrieval using the [Rio library](https://github.com/oxigraph/rio).
- [SPARQL Query Results XML Format](http://www.w3.org/TR/rdf-sparql-XMLres/), [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/) and [SPARQL 1.1 Query Results CSV and TSV Formats](https://www.w3.org/TR/sparql11-results-csv-tsv/).
A preliminary benchmark [is provided](bench/README.md). There is also [a document describing Oxigraph technical architecture](https://github.com/oxigraph/oxigraph/wiki/Architecture). A preliminary benchmark [is provided](bench/README.md). There is also [a document describing Oxigraph technical architecture](https://github.com/oxigraph/oxigraph/wiki/Architecture).
## Development
The easiest way to set up the development environment is to use Visual Studio Code's [development containers](https://code.visualstudio.com/docs/remote/containers). Note that this requires Docker Desktop on Windows and Mac and Docker CE/EE on Linux.
Open the repository with Visual Studio Code and use the Command Palette to run `Remote-Containers: Rebuild Container`. This will re-open the project inside a development container with the Rust toolchain and Python dependencies installed. For more details on how the development container is set up, see [.devcontainer/devcontainer.json](.devcontainer/devcontainer.json) and [.devcontainer/Dockerfile](.devcontainer/Dockerfile).
For further development details, see the README in each of the respective sub-projects.
## Help ## Help
@ -46,18 +54,16 @@ Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discu
If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt/). If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt/).
## License ## License
This project is licensed under either of This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or - Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0) http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or - MIT license ([LICENSE-MIT](LICENSE-MIT) or
http://opensource.org/licenses/MIT) http://opensource.org/licenses/MIT)
at your option.
at your option.
### Contribution ### Contribution

@ -1,5 +1,4 @@
Pyoxigraph (Oxigraph for Python) # Pyoxigraph (Oxigraph for Python)
================================
[![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/) [![PyPI](https://img.shields.io/pypi/v/pyoxigraph)](https://pypi.org/project/pyoxigraph/)
![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyoxigraph) ![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyoxigraph)
@ -9,13 +8,13 @@ Pyoxigraph (Oxigraph for Python)
Pyoxigraph is a graph database library implementing the [SPARQL](https://www.w3.org/TR/sparql11-overview/) standard. Pyoxigraph is a graph database library implementing the [SPARQL](https://www.w3.org/TR/sparql11-overview/) standard.
It is a Python library written on top of [Oxigraph](https://crates.io/crates/oxigraph). It is a Python library written on top of [Oxigraph](https://crates.io/crates/oxigraph).
Pyoxigraph offers two stores with [SPARQL 1.1](https://www.w3.org/TR/sparql11-overview/) capabilities. Pyoxigraph offers two stores with [SPARQL 1.1](https://www.w3.org/TR/sparql11-overview/) capabilities.
One of the store is in-memory, and the other one is disk based. One of the store is in-memory, and the other one is disk based.
It also provides a set of utility functions for reading, writing and processing RDF files in It also provides a set of utility functions for reading, writing and processing RDF files in
[Turtle](https://www.w3.org/TR/turtle/), [Turtle](https://www.w3.org/TR/turtle/),
[TriG](https://www.w3.org/TR/trig/), [TriG](https://www.w3.org/TR/trig/),
[N-Triples](https://www.w3.org/TR/n-triples/), [N-Triples](https://www.w3.org/TR/n-triples/),
[N-Quads](https://www.w3.org/TR/n-quads/) and [N-Quads](https://www.w3.org/TR/n-quads/) and
[RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/). [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/).
@ -32,7 +31,6 @@ Pyoxigraph documentation is [available on the Oxigraph website](https://oxigraph
To build and install the development version of pyoxigraph you need to clone this git repository To build and install the development version of pyoxigraph you need to clone this git repository
and to run `pip install .` in the `python` directory (the one this README is in). and to run `pip install .` in the `python` directory (the one this README is in).
## Help ## Help
Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discussions) or [the Gitter chat](https://gitter.im/oxigraph/community) to ask questions or talk about Oxigraph. Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discussions) or [the Gitter chat](https://gitter.im/oxigraph/community) to ask questions or talk about Oxigraph.
@ -40,7 +38,6 @@ Feel free to use [GitHub discussions](https://github.com/oxigraph/oxigraph/discu
If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt). If you need advanced support or are willing to pay to get some extra features, feel free to reach out to [Tpt](https://github.com/Tpt).
## How to contribute ## How to contribute
Pyoxigraph is written in Rust using [PyO3](https://github.com/PyO3/pyo3). Pyoxigraph is written in Rust using [PyO3](https://github.com/PyO3/pyo3).
@ -49,21 +46,34 @@ Pyoxigraph is built using [Maturin](https://github.com/PyO3/maturin).
Maturin could be installed using the `pip install 'maturin>=0.9,<0.10'`. Maturin could be installed using the `pip install 'maturin>=0.9,<0.10'`.
To install a development version of Oxigraph just run `maturin develop` in this README directory. To install a development version of Oxigraph just run `maturin develop` in this README directory.
### Tests
The Python bindings tests are written in Python. The Python bindings tests are written in Python.
To run them use `python -m unittest` in the `tests` directory. To run them use `python -m unittest` in the `tests` directory.
### Docs
The Sphinx documentation can be generated and viewed in the browser using the following command:
```
sphinx-autobuild docs docs/_build/html
```
Note that you will need to have [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) installed. This should be installed already if you are using this repository's development container.
Alternatively, you can use `sphinx-build` with Python's `http.server` to achieve the same thing.
## License ## License
This project is licensed under either of This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or - Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0) http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or - MIT license ([LICENSE-MIT](../LICENSE-MIT) or
http://opensource.org/licenses/MIT) http://opensource.org/licenses/MIT)
at your option. at your option.
### Contribution ### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Oxigraph by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Oxigraph by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

@ -22,7 +22,7 @@ exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
# -- Options for HTML output ------------------------------------------------- # -- Options for HTML output -------------------------------------------------
html_theme = "classic" html_theme = "furo"
html_static_path = [] html_static_path = []
html_logo = "../../logo.svg" html_logo = "../../logo.svg"
html_favicon = "../../logo.svg" html_favicon = "../../logo.svg"

Loading…
Cancel
Save