protein-quest 0.3.2__tar.gz → 0.8.0__tar.gz

{protein_quest-0.3.2 → protein_quest-0.8.0}/.github/workflows/ci.yml

@@ -27,20 +27,11 @@ jobs:
       - name: Run tests
         run: |
           uv run pytest --cov --cov-report=xml
-          echo $? > pytest-exitcode
-        continue-on-error: true
-      # Always upload coverage, even if tests fail
       - name: Run codacy-coverage-reporter
         uses: codacy/codacy-coverage-reporter-action@v1.3.0
         with:
           project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
           coverage-reports: coverage.xml
-      - name: Fail job if pytest failed
-        run: |
-          if [ -f pytest-exitcode ] && [ "$(cat pytest-exitcode)" -ne 0 ]; then
-            echo "Pytest failed, failing job."
-            exit 1
-          fi
   build:
     name: build
     runs-on: ubuntu-latest

{protein_quest-0.3.2 → protein_quest-0.8.0}/.github/workflows/pages.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
   workflow_dispatch:
+  pull_request:
 
 permissions:
   contents: read
@@ -13,7 +14,7 @@ permissions:
 
 # Only have one deployment in progress at a time
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: true
 
 jobs:
@@ -32,6 +33,10 @@ jobs:
       - name: Build MkDocs site
         run: |
           uv run mkdocs build
+        env:
+          # Force colored output from rich library
+          TTY_COMPATIBLE: '1'
+          TTY_INTERACTIVE: '0'
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
@@ -42,6 +47,9 @@ jobs:
     # Add a dependency to the build job
     needs: build
 
+    # Only deploy on pushes to main or manual trigger of main branch
+    if: github.ref == 'refs/heads/main'
+
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:
       pages: write      # to deploy to Pages

{protein_quest-0.3.2 → protein_quest-0.8.0}/.gitignore

@@ -73,4 +73,17 @@ venv.bak/
 /docs/pdb_files/
 /docs/density_filtered/
 /site
-/mysession/
+/mysession/
+# Paths generated in README.md examples
+uniprot_accs.txt
+pdbe.csv
+alphafold.csv
+emdbs.csv
+interaction-partners-of-Q05471.txt
+complexes.csv
+downloads-af/
+downloads-emdb/
+downloads-pdbe/
+filtered/
+filtered-chains/
+filtered-ss/

protein_quest-0.8.0/.python-version

@@ -0,0 +1 @@
+3.13

{protein_quest-0.3.2 → protein_quest-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protein_quest
-Version: 0.3.2
+Version: 0.8.0
 Summary: Search/retrieve/filter proteins and protein structures
 Project-URL: Homepage, https://github.com/haddocking/protein-quest
 Project-URL: Issues, https://github.com/haddocking/protein-quest/issues
@@ -11,21 +11,23 @@ Requires-Python: >=3.13
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: aiohttp-retry>=2.9.1
 Requires-Dist: aiohttp[speedups]>=3.11.18
-Requires-Dist: aiopath>=0.7.7
 Requires-Dist: attrs>=25.3.0
 Requires-Dist: cattrs[orjson]>=24.1.3
 Requires-Dist: dask>=2025.5.1
 Requires-Dist: distributed>=2025.5.1
 Requires-Dist: gemmi>=0.7.3
+Requires-Dist: mmcif>=0.92.0
+Requires-Dist: platformdirs>=4.3.8
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: rich-argparse>=1.7.1
 Requires-Dist: rich>=14.0.0
+Requires-Dist: shtab>=1.7.2
 Requires-Dist: sparqlwrapper>=2.0.0
 Requires-Dist: tqdm>=4.67.1
 Requires-Dist: yarl>=1.20.1
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=2.11.3; extra == 'mcp'
-Requires-Dist: pydantic>=2.11.7; extra == 'mcp'
+Requires-Dist: pydantic>=2.12.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # protein-quest
@@ -47,6 +49,10 @@ It uses
 - [gemmi](https://project-gemmi.github.io/) to work with macromolecular models.
 - [dask-distributed](https://docs.dask.org/en/latest/) to compute in parallel.
 
+The package is used by
+
+- [protein-detective](https://github.com/haddocking/protein-detective)
+
 An example workflow:
 
 ```mermaid
@@ -56,19 +62,29 @@ graph TB;
     searchuniprot --> |uniprot_accessions|searchpdbe[/Search PDBe/]
     searchuniprot --> |uniprot_accessions|searchaf[/Search Alphafold/]
     searchuniprot -. uniprot_accessions .-> searchemdb[/Search EMDB/]
+    searchuniprot -. uniprot_accessions .-> searchuniprotdetails[/Search UniProt details/]
+    searchintactionpartners[/Search interaction partners/] -.-x |uniprot_accessions|searchuniprot
+    searchcomplexes[/Search complexes/]
     searchpdbe -->|pdb_ids|fetchpdbe[Retrieve PDBe]
     searchaf --> |uniprot_accessions|fetchad(Retrieve AlphaFold)
     searchemdb -. emdb_ids .->fetchemdb[Retrieve EMDB]
-    fetchpdbe -->|mmcif_files_with_uniprot_acc| chainfilter{{Filter on chain of uniprot}}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
     chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
-    fetchad -->|pdb_files| confidencefilter{{Filter out low confidence}}
+    fetchad -->|mmcif_files| confidencefilter{{Filter out low confidence}}
     confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
     residuefilter --> |mmcif_files| ssfilter
+    ssfilter -. mmcif_files .-> convert2cif([Convert to cif])
+    ssfilter -. mmcif_files .-> convert2uniprot_accessions([Convert to UniProt accessions])
     classDef dashedBorder stroke-dasharray: 5 5;
     goterm:::dashedBorder
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
+    searchuniprotdetails:::dashedBorder
+    convert2cif:::dashedBorder
+    convert2uniprot_accessions:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -90,13 +106,16 @@ The main entry point is the `protein-quest` command line tool which has multiple
 
 To use programmaticly, see the [Jupyter notebooks](https://www.bonvinlab.org/protein-quest/notebooks) and [API documentation](https://www.bonvinlab.org/protein-quest/autoapi/summary/).
 
+While downloading or copying files it uses a global cache (located at `~/.cache/protein-quest`) and hardlinks to save disk space and improve speed.
+This behavior can be customized with the `--no-cache`, `--cache-dir`, and `--copy-method` command line arguments.
+
 ### Search Uniprot accessions
 
 ```shell
 protein-quest search uniprot \
     --taxon-id 9606 \
     --reviewed \
-    --subcellular-location-uniprot nucleus \
+    --subcellular-location-uniprot "nucleus" \
     --subcellular-location-go GO:0005634 \
     --molecular-function-go GO:0003677 \
     --limit 100 \
@@ -136,7 +155,7 @@ protein-quest retrieve pdbe pdbe.csv downloads-pdbe/
 protein-quest retrieve alphafold alphafold.csv downloads-af/
 ```
 
-For each entry downloads the summary.json and cif file.
+For each entry downloads the cif file.
 
 ### To retrieve EMDB volume files
 
@@ -179,7 +198,7 @@ protein-quest filter residue  \
 
 ### To filter on secondary structure
 
-To filter on structure being mostly alpha helices and have no beta sheets.
+To filter on structure being mostly alpha helices and have no beta sheets. See the following [notebook](https://www.bonvinlab.org/protein-detective/SSE_elements.html) to determine the ratio of secondary structure elements.
 
 ```shell
 protein-quest filter secondary-structure \
@@ -204,6 +223,63 @@ You can use following command to search for a Gene Ontology (GO) term.
 protein-quest search go --limit 5 --aspect cellular_component apoptosome -
 ```
 
+### Search for interaction partners
+
+Use https://www.ebi.ac.uk/complexportal to find interaction partners of given UniProt accession.
+
+```shell
+protein-quest search interaction-partners Q05471 interaction-partners-of-Q05471.txt
+```
+
+The `interaction-partners-of-Q05471.txt` file contains uniprot accessions (one per line).
+
+### Search for complexes
+
+Given Uniprot accessions search for macromolecular complexes at https://www.ebi.ac.uk/complexportal
+and return the complex entries and their members.
+
+```shell
+echo Q05471 | protein-quest search complexes - complexes.csv
+```
+
+The `complexes.csv` looks like
+
+```csv
+query_protein,complex_id,complex_url,complex_title,members
+Q05471,CPX-2122,https://www.ebi.ac.uk/complexportal/complex/CPX-2122,Swr1 chromatin remodelling complex,P31376;P35817;P38326;P53201;P53930;P60010;P80428;Q03388;Q03433;Q03940;Q05471;Q06707;Q12464;Q12509
+```
+
+### Search for UniProt details
+
+To get details (like protein name, sequence length, organism) for a list of UniProt accessions.
+
+```shell
+protein-quest search uniprot-details uniprot_accs.txt uniprot_details.csv
+```
+
+The `uniprot_details.csv` looks like:
+
+```csv
+uniprot_accession,uniprot_id,sequence_length,reviewed,protein_name,taxon_id,taxon_name
+A0A087WUV0,ZN892_HUMAN,522,True,Zinc finger protein 892,9606,Homo sapiens
+```
+
+### Convert structure files to .cif format
+
+Some tools (for example [powerfit](https://github.com/haddocking/powerfit)) only work with `.cif` files and not `*.cif.gz` or `*.bcif` files.
+
+```shell
+protein-quest convert structures --format cif --output-dir ./filtered-cif ./filtered-ss
+```
+
+### Convert structure files to UniProt accessions
+
+After running some filters you might want to know which UniProt accessions are still present in the filtered structures.
+
+```shell
+protein-quest convert uniprot ./filtered-ss uniprot_accs.filtered.txt
+```
+
 ##  Model Context Protocol (MCP) server
 
 Protein quest can also help LLMs like Claude Sonnet 4 by providing a [set of tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools-ai-actions) for protein structures.
@@ -224,6 +300,26 @@ protein-quest mcp
 
 The mcp server contains an prompt template to search/retrieve/filter candidate structures.
 
+## Shell autocompletion
+
+The `protein-quest` command line tool supports shell autocompletion using [shtab](https://shtab.readthedocs.io/).
+
+Initialize for bash shell with:
+
+```shell
+mkdir -p ~/.local/share/bash-completion/completions
+protein-quest --print-completion bash > ~/.local/share/bash-completion/completions/protein-quest
+```
+
+Initialize for zsh shell with:
+
+```shell
+mkdir -p ~/.local/share/zsh/site-functions
+protein-quest --print-completion zsh > ~/.local/share/zsh/site-functions/_protein-quest
+fpath=("$HOME/.local/share/zsh/site-functions" $fpath)
+autoload -Uz compinit && compinit
+```
+
 ## Contributing
 
 For development information and contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).

{protein_quest-0.3.2 → protein_quest-0.8.0}/README.md

@@ -17,6 +17,10 @@ It uses
 - [gemmi](https://project-gemmi.github.io/) to work with macromolecular models.
 - [dask-distributed](https://docs.dask.org/en/latest/) to compute in parallel.
 
+The package is used by
+
+- [protein-detective](https://github.com/haddocking/protein-detective)
+
 An example workflow:
 
 ```mermaid
@@ -26,19 +30,29 @@ graph TB;
     searchuniprot --> |uniprot_accessions|searchpdbe[/Search PDBe/]
     searchuniprot --> |uniprot_accessions|searchaf[/Search Alphafold/]
     searchuniprot -. uniprot_accessions .-> searchemdb[/Search EMDB/]
+    searchuniprot -. uniprot_accessions .-> searchuniprotdetails[/Search UniProt details/]
+    searchintactionpartners[/Search interaction partners/] -.-x |uniprot_accessions|searchuniprot
+    searchcomplexes[/Search complexes/]
     searchpdbe -->|pdb_ids|fetchpdbe[Retrieve PDBe]
     searchaf --> |uniprot_accessions|fetchad(Retrieve AlphaFold)
     searchemdb -. emdb_ids .->fetchemdb[Retrieve EMDB]
-    fetchpdbe -->|mmcif_files_with_uniprot_acc| chainfilter{{Filter on chain of uniprot}}
+    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
     chainfilter --> |mmcif_files| residuefilter{{Filter on chain length}}
-    fetchad -->|pdb_files| confidencefilter{{Filter out low confidence}}
+    fetchad -->|mmcif_files| confidencefilter{{Filter out low confidence}}
     confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
     residuefilter --> |mmcif_files| ssfilter
+    ssfilter -. mmcif_files .-> convert2cif([Convert to cif])
+    ssfilter -. mmcif_files .-> convert2uniprot_accessions([Convert to UniProt accessions])
     classDef dashedBorder stroke-dasharray: 5 5;
     goterm:::dashedBorder
     taxonomy:::dashedBorder
     searchemdb:::dashedBorder
     fetchemdb:::dashedBorder
+    searchintactionpartners:::dashedBorder
+    searchcomplexes:::dashedBorder
+    searchuniprotdetails:::dashedBorder
+    convert2cif:::dashedBorder
+    convert2uniprot_accessions:::dashedBorder
 ```
 
 (Dotted nodes and edges are side-quests.)
@@ -60,13 +74,16 @@ The main entry point is the `protein-quest` command line tool which has multiple
 
 To use programmaticly, see the [Jupyter notebooks](https://www.bonvinlab.org/protein-quest/notebooks) and [API documentation](https://www.bonvinlab.org/protein-quest/autoapi/summary/).
 
+While downloading or copying files it uses a global cache (located at `~/.cache/protein-quest`) and hardlinks to save disk space and improve speed.
+This behavior can be customized with the `--no-cache`, `--cache-dir`, and `--copy-method` command line arguments.
+
 ### Search Uniprot accessions
 
 ```shell
 protein-quest search uniprot \
     --taxon-id 9606 \
     --reviewed \
-    --subcellular-location-uniprot nucleus \
+    --subcellular-location-uniprot "nucleus" \
     --subcellular-location-go GO:0005634 \
     --molecular-function-go GO:0003677 \
     --limit 100 \
@@ -106,7 +123,7 @@ protein-quest retrieve pdbe pdbe.csv downloads-pdbe/
 protein-quest retrieve alphafold alphafold.csv downloads-af/
 ```
 
-For each entry downloads the summary.json and cif file.
+For each entry downloads the cif file.
 
 ### To retrieve EMDB volume files
 
@@ -149,7 +166,7 @@ protein-quest filter residue  \
 
 ### To filter on secondary structure
 
-To filter on structure being mostly alpha helices and have no beta sheets.
+To filter on structure being mostly alpha helices and have no beta sheets. See the following [notebook](https://www.bonvinlab.org/protein-detective/SSE_elements.html) to determine the ratio of secondary structure elements.
 
 ```shell
 protein-quest filter secondary-structure \
@@ -174,6 +191,63 @@ You can use following command to search for a Gene Ontology (GO) term.
 protein-quest search go --limit 5 --aspect cellular_component apoptosome -
 ```
 
+### Search for interaction partners
+
+Use https://www.ebi.ac.uk/complexportal to find interaction partners of given UniProt accession.
+
+```shell
+protein-quest search interaction-partners Q05471 interaction-partners-of-Q05471.txt
+```
+
+The `interaction-partners-of-Q05471.txt` file contains uniprot accessions (one per line).
+
+### Search for complexes
+
+Given Uniprot accessions search for macromolecular complexes at https://www.ebi.ac.uk/complexportal
+and return the complex entries and their members.
+
+```shell
+echo Q05471 | protein-quest search complexes - complexes.csv
+```
+
+The `complexes.csv` looks like
+
+```csv
+query_protein,complex_id,complex_url,complex_title,members
+Q05471,CPX-2122,https://www.ebi.ac.uk/complexportal/complex/CPX-2122,Swr1 chromatin remodelling complex,P31376;P35817;P38326;P53201;P53930;P60010;P80428;Q03388;Q03433;Q03940;Q05471;Q06707;Q12464;Q12509
+```
+
+### Search for UniProt details
+
+To get details (like protein name, sequence length, organism) for a list of UniProt accessions.
+
+```shell
+protein-quest search uniprot-details uniprot_accs.txt uniprot_details.csv
+```
+
+The `uniprot_details.csv` looks like:
+
+```csv
+uniprot_accession,uniprot_id,sequence_length,reviewed,protein_name,taxon_id,taxon_name
+A0A087WUV0,ZN892_HUMAN,522,True,Zinc finger protein 892,9606,Homo sapiens
+```
+
+### Convert structure files to .cif format
+
+Some tools (for example [powerfit](https://github.com/haddocking/powerfit)) only work with `.cif` files and not `*.cif.gz` or `*.bcif` files.
+
+```shell
+protein-quest convert structures --format cif --output-dir ./filtered-cif ./filtered-ss
+```
+
+### Convert structure files to UniProt accessions
+
+After running some filters you might want to know which UniProt accessions are still present in the filtered structures.
+
+```shell
+protein-quest convert uniprot ./filtered-ss uniprot_accs.filtered.txt
+```
+
 ##  Model Context Protocol (MCP) server
 
 Protein quest can also help LLMs like Claude Sonnet 4 by providing a [set of tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools-ai-actions) for protein structures.
@@ -194,6 +268,26 @@ protein-quest mcp
 
 The mcp server contains an prompt template to search/retrieve/filter candidate structures.
 
+## Shell autocompletion
+
+The `protein-quest` command line tool supports shell autocompletion using [shtab](https://shtab.readthedocs.io/).
+
+Initialize for bash shell with:
+
+```shell
+mkdir -p ~/.local/share/bash-completion/completions
+protein-quest --print-completion bash > ~/.local/share/bash-completion/completions/protein-quest
+```
+
+Initialize for zsh shell with:
+
+```shell
+mkdir -p ~/.local/share/zsh/site-functions
+protein-quest --print-completion zsh > ~/.local/share/zsh/site-functions/_protein-quest
+fpath=("$HOME/.local/share/zsh/site-functions" $fpath)
+autoload -Uz compinit && compinit
+```
+
 ## Contributing
 
 For development information and contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).