Metadata-Version: 2.4
Name: sparql-api-codegen
Version: 0.0.1
Summary: Automatically generate python API package from a SPARQL endpoint using its VoID descriptive metadata
Project-URL: Homepage, https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen
Project-URL: Documentation, https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen
Project-URL: History, https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen/releases
Project-URL: Tracker, https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen/issues
Project-URL: Source, https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen
Author-email: Vincent Emonet <vincent.emonet@sib.swiss>
Maintainer-email: Vincent Emonet <vincent.emonet@sib.swiss>
License: MIT License
        
        Copyright (c) 2024-present SIB Swiss Institute of Bioinformatics
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.txt
Keywords: Python,SPARQL
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: requests
Requires-Dist: typer>=0.12.0
Provides-Extra: test
Requires-Dist: mypy>=1.4.1; extra == 'test'
Requires-Dist: pip-tools; extra == 'test'
Requires-Dist: pre-commit; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest>=8.3.3; extra == 'test'
Requires-Dist: types-requests; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">

# ✨ SPARQL API code generator 🐍

</div>

A CLI tool to automatically generate a python package from a SPARQL endpoint VoID description.

It will generate a folder with all requirements for publishing a modern python package containing the classes to automatically work with the data in the endpoint.

Features:

* Each class in the endpoint will be defined as a python class, with fields for each predicates available on a class.
* It will use the classes and predicates labels from their ontology when possible to generate the python classes and their fields
* Type annotations are used for better autocompletion
* Fields of a class are retrieved when the field is called (lazy 🦥)

## 🪄 Usage

> Requirements: Python >=3.9

1. Install the package with `pip` or `pipx`:

   ```sh
   pipx install sparql-api-codegen
   ```

2. Generate the code for a SPARQL endpoint which contains a SPARQL Service Description:

   ```sh
   sparql-api-codegen <sparql-endpoint-url> <folder-for-generated-python-pkg> -i <iri-of-class-to-ignore>
   ```

3. Once the folders have been generated you can get into the folder, check and improve the instructions to run in the `README.md`, improve the metadata in the `pyproject.toml`

Optionally you can ignore some classes. For some endpoints this will be required if the label generated for 2 classes are identical, e.g. for Bgee:

```sh
sparql-api-codegen "https://www.bgee.org/sparql/" "bgee-api" \
	-i http://purl.obolibrary.org/obo/CARO_0000000 \
	-i http://purl.obolibrary.org/obo/SO_0000704 \
	-i http://purl.obolibrary.org/obo/NCIT_C14250
```

Example python API for Bgee:

```python
from bgee_api import AnatomicalEntity, Gene, GeneExpressionExperimentCondition


if __name__ == "__main__":
    all_anats = AnatomicalEntity.get()
    print(len(all_anats), all_anats[0])

    anat = AnatomicalEntity("http://purl.obolibrary.org/obo/AEO_0000013")
    print(anat)
    print(anat.label)
    print(anat.expresses)

    gene= Gene("http://omabrowser.org/ontology/oma#GENE_ENSMUSG00000053483")
    print(gene.label)

    cond = GeneExpressionExperimentCondition("http://bgee.org/#EXPRESSION_CONDITION_101909")
    print(cond.has_a_developmental_stage)
    print(cond.has_anatomical_entity)
```

For UniProt:

```sh
sparql-api-codegen "https://sparql.uniprot.org/sparql/" "uniprot-api" \
	-i http://biohackathon.org/resource/faldo#Region
```

## 🧑‍💻 Development setup

The final section of the README is for if you want to run the package in development, and get involved by making a code contribution.


### 📥️ Clone

Clone the repository:

```bash
git clone https://github.com/TRIPLE-CHIST-ERA/sparql-api-codegen
cd sparql-api-codegen
```

### 🐣 Install dependencies

Install [Hatch](https://hatch.pypa.io), a modern build system, as well as project and virtual env management tool recommended by the Python Packaging Authority. This will automatically handle virtual environments and make sure all dependencies are installed when you run a script in the project:

```bash
pipx install hatch
```

Or you could install in your favorite virtual env:

```bash
pip install -e ".[test]"
```

### 🛠️ Develop

Test with the Bgee endpoint:

```bash
hatch run sparql-api-codegen "https://www.bgee.org/sparql/" "bgee-api" \
    -i http://purl.obolibrary.org/obo/CARO_0000000 \
    -i http://purl.obolibrary.org/obo/SO_0000704 \
    -i http://purl.obolibrary.org/obo/NCIT_C14250
```

### ☑️ Run tests

Make sure the existing tests still work by running the test suite and linting checks. Note that any pull requests to the fairworkflows repository on github will automatically trigger running of the test suite;

```bash
hatch run test
```

To display all logs when debugging:

```bash
hatch run test -s
```

### ♻️ Reset the environment

In case you are facing issues with dependencies not updating properly you can easily reset the virtual environment with:

```bash
hatch env prune
```

Manually trigger installing the dependencies in a local virtual environment:

```bash
hatch -v env create
```

### 🏷️ New release process

The deployment of new releases is done automatically by a GitHub Action workflow when a new release is created on GitHub. To release a new version:

1. Make sure the `PYPI_TOKEN` secret has been defined in the GitHub repository (in Settings > Secrets > Actions). You can get an API token from PyPI at [pypi.org/manage/account](https://pypi.org/manage/account).
2. Increment the `version` number in the `pyproject.toml` file in the root folder of the repository.

    ```bash
    hatch version fix
    ```

3. Create a new release on GitHub, which will automatically trigger the publish workflow, and publish the new release to PyPI.

You can also build and publish from your computer:

```bash
hatch build
hatch publish
```

### TODO

- Bulk load with preloaded fields

  ```python
  all_anats_preloaded: list[AnatomicalEntity] = bulk_load(AnatomicalEntity, ["label", "expresses"])
  # Or
  all_anats_preloaded: list[AnatomicalEntity] = AnatomicalEntity.get(["label", "expresses"])
  ```

  > Allow also to pass a list of IRI (optional, if not we get all?)

- Returns pandas matrix with filters?

  ```python
  pandas_matrix = BiologicalEntity.get_matrix(
      filter_has_a_developmental_stage="http://some_dev_stage",
      filter_has_anatomical_entity="some anatomical entity",
  )
  ```

  > Also enable to filter on labels instead of IRI?
