protein-quest 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

protein_quest/cli.py

@@ -6,14 +6,15 @@ import csv
 import logging
 import os
 import sys
-from collections.abc import Callable, Generator, Iterable
+from collections.abc import Callable, Generator, Iterable, Sequence
+from contextlib import suppress
 from importlib.util import find_spec
-from io import TextIOWrapper
+from io import BytesIO, TextIOWrapper
 from pathlib import Path
 from textwrap import dedent
 
 from cattrs import structure
-from rich import print as rprint
+from rich.console import Console
 from rich.logging import RichHandler
 from rich.markdown import Markdown
 from rich.panel import Panel
@@ -24,7 +25,7 @@ from protein_quest.__version__ import __version__
 from protein_quest.alphafold.confidence import ConfidenceFilterQuery, filter_files_on_confidence
 from protein_quest.alphafold.fetch import DownloadableFormat, downloadable_formats
 from protein_quest.alphafold.fetch import fetch_many as af_fetch
-from protein_quest.converter import converter
+from protein_quest.converter import PositiveInt, converter
 from protein_quest.emdb import fetch as emdb_fetch
 from protein_quest.filters import filter_files_on_chain, filter_files_on_residues
 from protein_quest.go import Aspect, allowed_aspects, search_gene_ontology_term, write_go_terms_to_csv
@@ -32,15 +33,20 @@ from protein_quest.io import (
     convert_to_cif_files,
     glob_structure_files,
     locate_structure_file,
+    read_structure,
     valid_structure_file_extensions,
 )
 from protein_quest.pdbe import fetch as pdbe_fetch
 from protein_quest.ss import SecondaryStructureFilterQuery, filter_files_on_secondary_structure
+from protein_quest.structure import structure2uniprot_accessions
 from protein_quest.taxonomy import SearchField, _write_taxonomy_csv, search_fields, search_taxon
 from protein_quest.uniprot import (
     ComplexPortalEntry,
-    PdbResult,
+    PdbResults,
     Query,
+    UniprotDetails,
+    filter_pdb_results_on_chain_length,
+    map_uniprot_accessions2uniprot_details,
     search4af,
     search4emdb,
     search4interaction_partners,
@@ -58,6 +64,8 @@ from protein_quest.utils import (
     user_cache_root_dir,
 )
 
+console = Console(stderr=True)
+rprint = console.print
 logger = logging.getLogger(__name__)
 
 
@@ -98,6 +106,8 @@ def _add_search_uniprot_parser(subparsers: argparse._SubParsersAction):
         action="append",
         help="GO term(s) for molecular function (e.g. GO:0003677). Can be given multiple times.",
     )
+    parser.add_argument("--min-sequence-length", type=int, help="Minimum length of the canonical sequence.")
+    parser.add_argument("--max-sequence-length", type=int, help="Maximum length of the canonical sequence.")
     parser.add_argument("--limit", type=int, default=10_000, help="Maximum number of uniprot accessions to return")
     parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
 
@@ -111,7 +121,7 @@ def _add_search_pdbe_parser(subparsers: argparse._SubParsersAction):
         formatter_class=ArgumentDefaultsRichHelpFormatter,
     )
     parser.add_argument(
-        "uniprot_accs",
+        "uniprot_accessions",
         type=argparse.FileType("r", encoding="UTF-8"),
         help="Text file with UniProt accessions (one per line). Use `-` for stdin.",
     )
@@ -119,15 +129,27 @@ def _add_search_pdbe_parser(subparsers: argparse._SubParsersAction):
         "output_csv",
         type=argparse.FileType("w", encoding="UTF-8"),
         help=dedent("""\
-            Output CSV with `uniprot_acc`, `pdb_id`, `method`, `resolution`, `uniprot_chains`, `chain` columns.
+            Output CSV with following columns:
+            `uniprot_accession`, `pdb_id`, `method`, `resolution`, `uniprot_chains`, `chain`, `chain_length`.
             Where `uniprot_chains` is the raw UniProt chain string, for example `A=1-100`.
-            and where `chain` is the first chain from `uniprot_chains`, for example `A`.
+            and where `chain` is the first chain from `uniprot_chains`, for example `A`
+            and `chain_length` is the length of the chain, for example `100`.
             Use `-` for stdout.
         """),
     )
     parser.add_argument(
         "--limit", type=int, default=10_000, help="Maximum number of PDB uniprot accessions combinations to return"
     )
+    parser.add_argument(
+        "--min-residues",
+        type=int,
+        help="Minimum number of residues required in the chain mapped to the UniProt accession.",
+    )
+    parser.add_argument(
+        "--max-residues",
+        type=int,
+        help="Maximum number of residues allowed in chain mapped to the UniProt accession.",
+    )
     parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
 
 
@@ -140,7 +162,7 @@ def _add_search_alphafold_parser(subparsers: argparse._SubParsersAction):
         formatter_class=ArgumentDefaultsRichHelpFormatter,
     )
     parser.add_argument(
-        "uniprot_accs",
+        "uniprot_accessions",
         type=argparse.FileType("r", encoding="UTF-8"),
         help="Text file with UniProt accessions (one per line). Use `-` for stdin.",
     )
@@ -149,6 +171,8 @@ def _add_search_alphafold_parser(subparsers: argparse._SubParsersAction):
         type=argparse.FileType("w", encoding="UTF-8"),
         help="Output CSV with AlphaFold IDs per UniProt accession. Use `-` for stdout.",
     )
+    parser.add_argument("--min-sequence-length", type=int, help="Minimum length of the canonical sequence.")
+    parser.add_argument("--max-sequence-length", type=int, help="Maximum length of the canonical sequence.")
     parser.add_argument(
         "--limit", type=int, default=10_000, help="Maximum number of Alphafold entry identifiers to return"
     )
@@ -247,7 +271,7 @@ def _add_search_interaction_partners_parser(subparsers: argparse._SubParsersActi
         formatter_class=ArgumentDefaultsRichHelpFormatter,
     )
     parser.add_argument(
-        "uniprot_acc",
+        "uniprot_accession",
         type=str,
         help="UniProt accession (for example P12345).",
     )
@@ -289,7 +313,7 @@ def _add_search_complexes_parser(subparsers: argparse._SubParsersAction):
         formatter_class=ArgumentDefaultsRichHelpFormatter,
     )
     parser.add_argument(
-        "uniprot_accs",
+        "uniprot_accessions",
         type=argparse.FileType("r", encoding="UTF-8"),
         help="Text file with UniProt accessions (one per line) as query for searching complexes. Use `-` for stdin.",
     )
@@ -302,6 +326,44 @@ def _add_search_complexes_parser(subparsers: argparse._SubParsersAction):
     parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
 
 
+def _add_search_uniprot_details_parser(subparsers: argparse._SubParsersAction):
+    """Add search uniprot details subcommand parser."""
+    description = dedent("""\
+        Retrieve UniProt details for given UniProt accessions
+        from the Uniprot SPARQL endpoint.
+
+        The output CSV file has the following columns:
+
+        - uniprot_accession: UniProt accession.
+        - uniprot_id: UniProt ID (mnemonic).
+        - sequence_length: Length of the canonical sequence.
+        - reviewed: Whether the entry is reviewed (Swiss-Prot) or unreviewed (TrEMBL).
+        - protein_name: Recommended protein name.
+        - taxon_id: NCBI Taxonomy ID of the organism.
+        - taxon_name: Scientific name of the organism.
+
+        The order of the output CSV can be different from the input order.
+    """)
+    parser = subparsers.add_parser(
+        "uniprot-details",
+        help="Retrieve UniProt details for given UniProt accessions",
+        description=Markdown(description, style="argparse.text"),  # type: ignore using rich formatter makes this OK
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    parser.add_argument(
+        "uniprot_accessions",
+        type=argparse.FileType("r", encoding="UTF-8"),
+        help="Text file with UniProt accessions (one per line). Use `-` for stdin.",
+    )
+    parser.add_argument(
+        "output_csv",
+        type=argparse.FileType("w", encoding="UTF-8"),
+        help="Output CSV with UniProt details. Use `-` for stdout.",
+    )
+    parser.add_argument("--timeout", type=int, default=1_800, help="Maximum seconds to wait for query to complete")
+    parser.add_argument("--batch-size", type=int, default=1_000, help="Number of accessions to query per batch")
+
+
 def _add_copy_method_arguments(parser):
     parser.add_argument(
         "--copy-method",
@@ -387,6 +449,14 @@ def _add_retrieve_alphafold_parser(subparsers: argparse._SubParsersAction):
         action="store_true",
         help="Whether to gzip the downloaded files. Excludes summary files, they are always uncompressed.",
     )
+    parser.add_argument(
+        "--all-isoforms",
+        action="store_true",
+        help=(
+            "Whether to return all isoforms of each uniprot entry. "
+            "If not given then only the Alphafold entry for the canonical sequence is returned."
+        ),
+    )
     parser.add_argument(
         "--max-parallel-downloads",
         type=int,
@@ -575,6 +645,7 @@ def _add_search_subcommands(subparsers: argparse._SubParsersAction):
     _add_search_taxonomy_parser(subsubparsers)
     _add_search_interaction_partners_parser(subsubparsers)
     _add_search_complexes_parser(subsubparsers)
+    _add_search_uniprot_details_parser(subsubparsers)
 
 
 def _add_retrieve_subcommands(subparsers: argparse._SubParsersAction):
@@ -603,10 +674,39 @@ def _add_filter_subcommands(subparsers: argparse._SubParsersAction):
     _add_filter_ss_parser(subsubparsers)
 
 
-def _add_convert_subcommands(subparsers: argparse._SubParsersAction):
-    """Add convert command."""
+def _add_convert_uniprot_parser(subparsers: argparse._SubParsersAction):
+    """Add convert uniprot subcommand parser."""
+    parser = subparsers.add_parser(
+        "uniprot",
+        help="Convert structure files to list of UniProt accessions.",
+        description="Convert structure files to list of UniProt accessions. "
+        "Uniprot accessions are read from database reference of each structure.",
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    parser.add_argument(
+        "input_dir",
+        type=Path,
+        help=f"Directory with structure files. Supported extensions are {valid_structure_file_extensions}",
+    )
+    parser.add_argument(
+        "output",
+        type=argparse.FileType("wt", encoding="UTF-8"),
+        help="Output text file with UniProt accessions (one per line). Use '-' for stdout.",
+    )
+    parser.add_argument(
+        "--grouped",
+        action="store_true",
+        help="Whether to group accessions by structure file. "
+        "If set output changes to `<structure_file1>,<acc1>\\n<structure_file1>,<acc2>` format.",
+    )
+
+
+def _add_convert_structures_parser(subparsers: argparse._SubParsersAction):
+    """Add convert structures subcommand parser."""
     parser = subparsers.add_parser(
-        "convert", help="Convert structure files between formats", formatter_class=ArgumentDefaultsRichHelpFormatter
+        "structures",
+        help="Convert structure files between formats",
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
     )
     parser.add_argument(
         "input_dir",
@@ -630,6 +730,19 @@ def _add_convert_subcommands(subparsers: argparse._SubParsersAction):
     _add_copy_method_arguments(parser)
 
 
+def _add_convert_subcommands(subparsers: argparse._SubParsersAction):
+    """Add convert command and its subcommands."""
+    parser = subparsers.add_parser(
+        "convert",
+        help="Convert files between formats",
+        formatter_class=ArgumentDefaultsRichHelpFormatter,
+    )
+    subsubparsers = parser.add_subparsers(dest="convert_cmd", required=True)
+
+    _add_convert_structures_parser(subsubparsers)
+    _add_convert_uniprot_parser(subsubparsers)
+
+
 def _add_mcp_command(subparsers: argparse._SubParsersAction):
     """Add MCP command."""
 
@@ -667,12 +780,22 @@ def make_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _name_of(file: TextIOWrapper | BytesIO) -> str:
+    try:
+        return file.name
+    except AttributeError:
+        # In pytest BytesIO is used stdout which has no 'name' attribute
+        return "<stdout>"
+
+
 def _handle_search_uniprot(args):
     taxon_id = args.taxon_id
     reviewed = args.reviewed
     subcellular_location_uniprot = args.subcellular_location_uniprot
     subcellular_location_go = args.subcellular_location_go
     molecular_function_go = args.molecular_function_go
+    min_sequence_length = args.min_sequence_length
+    max_sequence_length = args.max_sequence_length
     limit = args.limit
     timeout = args.timeout
     output_file = args.output
@@ -684,54 +807,78 @@ def _handle_search_uniprot(args):
             "subcellular_location_uniprot": subcellular_location_uniprot,
             "subcellular_location_go": subcellular_location_go,
             "molecular_function_go": molecular_function_go,
+            "min_sequence_length": min_sequence_length,
+            "max_sequence_length": max_sequence_length,
         },
         Query,
     )
     rprint("Searching for UniProt accessions")
     accs = search4uniprot(query=query, limit=limit, timeout=timeout)
-    rprint(f"Found {len(accs)} UniProt accessions, written to {output_file.name}")
+    rprint(f"Found {len(accs)} UniProt accessions, written to {_name_of(output_file)}")
     _write_lines(output_file, sorted(accs))
 
 
 def _handle_search_pdbe(args):
-    uniprot_accs = args.uniprot_accs
+    uniprot_accessions = args.uniprot_accessions
     limit = args.limit
     timeout = args.timeout
     output_csv = args.output_csv
+    min_residues = converter.structure(args.min_residues, PositiveInt | None)  # pyright: ignore[reportArgumentType]
+    max_residues = converter.structure(args.max_residues, PositiveInt | None)  # pyright: ignore[reportArgumentType]
 
-    accs = set(_read_lines(uniprot_accs))
+    accs = set(_read_lines(uniprot_accessions))
     rprint(f"Finding PDB entries for {len(accs)} uniprot accessions")
     results = search4pdb(accs, limit=limit, timeout=timeout)
-    total_pdbs = sum([len(v) for v in results.values()])
-    rprint(f"Found {total_pdbs} PDB entries for {len(results)} uniprot accessions")
-    rprint(f"Written to {output_csv.name}")
+
+    raw_nr_results = len(results)
+    raw_total_pdbs = sum([len(v) for v in results.values()])
+    if min_residues or max_residues:
+        results = filter_pdb_results_on_chain_length(results, min_residues, max_residues)
+        total_pdbs = sum([len(v) for v in results.values()])
+        rprint(f"Before filtering found {raw_total_pdbs} PDB entries for {raw_nr_results} uniprot accessions.")
+        rprint(
+            f"After filtering on chain length ({min_residues}, {max_residues}) "
+            f"remained {total_pdbs} PDB entries for {len(results)} uniprot accessions."
+        )
+    else:
+        rprint(f"Found {raw_total_pdbs} PDB entries for {raw_nr_results} uniprot accessions")
+
     _write_pdbe_csv(output_csv, results)
+    rprint(f"Written to {_name_of(output_csv)}")
 
 
 def _handle_search_alphafold(args):
-    uniprot_accs = args.uniprot_accs
+    uniprot_accessions = args.uniprot_accessions
+    min_sequence_length = converter.structure(args.min_sequence_length, PositiveInt | None)  # pyright: ignore[reportArgumentType]
+    max_sequence_length = converter.structure(args.max_sequence_length, PositiveInt | None)  # pyright: ignore[reportArgumentType]
     limit = args.limit
     timeout = args.timeout
     output_csv = args.output_csv
 
-    accs = _read_lines(uniprot_accs)
+    accs = _read_lines(uniprot_accessions)
     rprint(f"Finding AlphaFold entries for {len(accs)} uniprot accessions")
-    results = search4af(accs, limit=limit, timeout=timeout)
-    rprint(f"Found {len(results)} AlphaFold entries, written to {output_csv.name}")
+    results = search4af(
+        accs,
+        min_sequence_length=min_sequence_length,
+        max_sequence_length=max_sequence_length,
+        limit=limit,
+        timeout=timeout,
+    )
+    rprint(f"Found {len(results)} AlphaFold entries, written to {_name_of(output_csv)}")
     _write_dict_of_sets2csv(output_csv, results, "af_id")
 
 
 def _handle_search_emdb(args):
-    uniprot_accs = args.uniprot_accs
+    uniprot_accessions = args.uniprot_accessions
     limit = args.limit
     timeout = args.timeout
     output_csv = args.output_csv
 
-    accs = _read_lines(uniprot_accs)
+    accs = _read_lines(uniprot_accessions)
     rprint(f"Finding EMDB entries for {len(accs)} uniprot accessions")
     results = search4emdb(accs, limit=limit, timeout=timeout)
     total_emdbs = sum([len(v) for v in results.values()])
-    rprint(f"Found {total_emdbs} EMDB entries, written to {output_csv.name}")
+    rprint(f"Found {total_emdbs} EMDB entries, written to {_name_of(output_csv)}")
     _write_dict_of_sets2csv(output_csv, results, "emdb_id")
 
 
@@ -746,7 +893,7 @@ def _handle_search_go(args):
     else:
         rprint(f"Searching for GO terms matching '{term}'")
     results = asyncio.run(search_gene_ontology_term(term, aspect=aspect, limit=limit))
-    rprint(f"Found {len(results)} GO terms, written to {output_csv.name}")
+    rprint(f"Found {len(results)} GO terms, written to {_name_of(output_csv)}")
     write_go_terms_to_csv(results, output_csv)
 
 
@@ -761,36 +908,49 @@ def _handle_search_taxonomy(args):
     else:
         rprint(f"Searching for taxon information matching '{query}'")
     results = asyncio.run(search_taxon(query=query, field=field, limit=limit))
-    rprint(f"Found {len(results)} taxons, written to {output_csv.name}")
+    rprint(f"Found {len(results)} taxons, written to {_name_of(output_csv)}")
     _write_taxonomy_csv(results, output_csv)
 
 
 def _handle_search_interaction_partners(args: argparse.Namespace):
-    uniprot_acc: str = args.uniprot_acc
+    uniprot_accession: str = args.uniprot_accession
     excludes: set[str] = set(args.exclude) if args.exclude else set()
     limit: int = args.limit
     timeout: int = args.timeout
     output_csv: TextIOWrapper = args.output_csv
 
-    rprint(f"Searching for interaction partners of '{uniprot_acc}'")
-    results = search4interaction_partners(uniprot_acc, excludes=excludes, limit=limit, timeout=timeout)
-    rprint(f"Found {len(results)} interaction partners, written to {output_csv.name}")
+    rprint(f"Searching for interaction partners of '{uniprot_accession}'")
+    results = search4interaction_partners(uniprot_accession, excludes=excludes, limit=limit, timeout=timeout)
+    rprint(f"Found {len(results)} interaction partners, written to {_name_of(output_csv)}")
     _write_lines(output_csv, results.keys())
 
 
 def _handle_search_complexes(args: argparse.Namespace):
-    uniprot_accs = args.uniprot_accs
+    uniprot_accessions = args.uniprot_accessions
     limit = args.limit
     timeout = args.timeout
     output_csv = args.output_csv
 
-    accs = _read_lines(uniprot_accs)
+    accs = _read_lines(uniprot_accessions)
     rprint(f"Finding complexes for {len(accs)} uniprot accessions")
     results = search4macromolecular_complexes(accs, limit=limit, timeout=timeout)
-    rprint(f"Found {len(results)} complexes, written to {output_csv.name}")
+    rprint(f"Found {len(results)} complexes, written to {_name_of(output_csv)}")
     _write_complexes_csv(results, output_csv)
 
 
+def _handle_search_uniprot_details(args: argparse.Namespace):
+    uniprot_accessions = args.uniprot_accessions
+    timeout = args.timeout
+    batch_size = args.batch_size
+    output_csv: TextIOWrapper = args.output_csv
+
+    accs = _read_lines(uniprot_accessions)
+    rprint(f"Retrieving UniProt entry details for {len(accs)} uniprot accessions")
+    results = list(map_uniprot_accessions2uniprot_details(accs, timeout=timeout, batch_size=batch_size))
+    _write_uniprot_details_csv(output_csv, results)
+    rprint(f"Retrieved details for {len(results)} UniProt entries, written to {_name_of(output_csv)}")
+
+
 def _initialize_cacher(args: argparse.Namespace) -> Cacher:
     if args.no_cache:
         return PassthroughCacher()
@@ -821,11 +981,12 @@ def _handle_retrieve_alphafold(args):
     max_parallel_downloads = args.max_parallel_downloads
     cacher = _initialize_cacher(args)
     gzip_files = args.gzip_files
+    all_isoforms = args.all_isoforms
 
     if what_formats is None:
         what_formats = {"summary", "cif"}
 
-    # TODO besides `uniprot_acc,af_id\n` csv also allow headless single column format
+    # TODO besides `uniprot_accession,af_id\n` csv also allow headless single column format
     #
     af_ids = _read_column_from_csv(alphafold_csv, "af_id")
     validated_what: set[DownloadableFormat] = structure(what_formats, set[DownloadableFormat])
@@ -837,6 +998,7 @@ def _handle_retrieve_alphafold(args):
         max_parallel_downloads=max_parallel_downloads,
         cacher=cacher,
         gzip_files=gzip_files,
+        all_isoforms=all_isoforms,
     )
     total_nr_files = sum(af.nr_of_files() for af in afs)
     rprint(f"Retrieved {total_nr_files} AlphaFold files and {len(afs)} summaries, written to {download_dir}")
@@ -891,11 +1053,11 @@ def _handle_filter_confidence(args: argparse.Namespace):
         if r.filtered_file:
             passed_count += 1
         if stats_file:
-            writer.writerow([r.input_file, r.count, r.filtered_file is not None, r.filtered_file])
+            writer.writerow([r.input_file, r.count, r.filtered_file is not None, r.filtered_file])  # pyright: ignore[reportPossiblyUnboundVariable]
 
     rprint(f"Filtered {passed_count} mmcif/PDB files by confidence, written to {output_dir} directory")
     if stats_file:
-        rprint(f"Statistics written to {stats_file.name}")
+        rprint(f"Statistics written to {_name_of(stats_file)}")
 
 
 def _handle_filter_chain(args):
@@ -961,13 +1123,13 @@ def _handle_filter_residue(args):
         input_files, output_dir, min_residues=min_residues, max_residues=max_residues, copy_method=copy_method
     ):
         if stats_file:
-            writer.writerow([r.input_file, r.residue_count, r.passed, r.output_file])
+            writer.writerow([r.input_file, r.residue_count, r.passed, r.output_file])  # pyright: ignore[reportPossiblyUnboundVariable]
         if r.passed:
             nr_passed += 1
 
     rprint(f"Wrote {nr_passed} files to {output_dir} directory.")
     if stats_file:
-        rprint(f"Statistics written to {stats_file.name}")
+        rprint(f"Statistics written to {_name_of(stats_file)}")
 
 
 def _handle_filter_ss(args):
@@ -1015,7 +1177,7 @@ def _handle_filter_ss(args):
             copyfile(input_file, output_file, copy_method)
             nr_passed += 1
         if stats_file:
-            writer.writerow(
+            writer.writerow(  # pyright: ignore[reportPossiblyUnboundVariable]
                 [
                     input_file,
                     result.stats.nr_residues,
@@ -1029,7 +1191,7 @@ def _handle_filter_ss(args):
             )
     rprint(f"Wrote {nr_passed} files to {output_dir} directory.")
     if stats_file:
-        rprint(f"Statistics written to {stats_file.name}")
+        rprint(f"Statistics written to {_name_of(stats_file)}")
 
 
 def _handle_mcp(args):
@@ -1045,9 +1207,30 @@ def _handle_mcp(args):
         mcp.run(transport=args.transport, host=args.host, port=args.port)
 
 
-def _handle_convert(args):
+def _handle_convert_uniprot(args):
+    input_dir = structure(args.input_dir, Path)
+    output_file: TextIOWrapper = args.output
+    grouped: bool = args.grouped
+    input_files = sorted(glob_structure_files(input_dir))
+    if grouped:
+        for input_file in tqdm(input_files, unit="file"):
+            s = read_structure(input_file)
+            uniprot_accessions = structure2uniprot_accessions(s)
+            _write_lines(
+                output_file, [f"{input_file},{uniprot_accession}" for uniprot_accession in sorted(uniprot_accessions)]
+            )
+    else:
+        uniprot_accessions: set[str] = set()
+        for input_file in tqdm(input_files, unit="file"):
+            s = read_structure(input_file)
+            uniprot_accessions.update(structure2uniprot_accessions(s))
+        _write_lines(output_file, sorted(uniprot_accessions))
+
+
+def _handle_convert_structures(args):
     input_dir = structure(args.input_dir, Path)
     output_dir = input_dir if args.output_dir is None else structure(args.output_dir, Path)
+    output_dir.mkdir(parents=True, exist_ok=True)
     copy_method: CopyMethod = structure(args.copy_method, CopyMethod)  # pyright: ignore[reportArgumentType]
 
     input_files = sorted(glob_structure_files(input_dir))
@@ -1070,7 +1253,8 @@ def _read_lines(file: TextIOWrapper) -> list[str]:
 
 
 def _make_sure_parent_exists(file: TextIOWrapper):
-    if file.name != "<stdout>":
+    # Can not create dir for stdout
+    with suppress(AttributeError):
         Path(file.name).parent.mkdir(parents=True, exist_ok=True)
 
 
@@ -1079,34 +1263,35 @@ def _write_lines(file: TextIOWrapper, lines: Iterable[str]):
     file.writelines(line + os.linesep for line in lines)
 
 
-def _write_pdbe_csv(path: TextIOWrapper, data: dict[str, set[PdbResult]]):
+def _write_pdbe_csv(path: TextIOWrapper, data: PdbResults):
     _make_sure_parent_exists(path)
-    fieldnames = ["uniprot_acc", "pdb_id", "method", "resolution", "uniprot_chains", "chain"]
+    fieldnames = ["uniprot_accession", "pdb_id", "method", "resolution", "uniprot_chains", "chain", "chain_length"]
     writer = csv.DictWriter(path, fieldnames=fieldnames)
     writer.writeheader()
-    for uniprot_acc, entries in sorted(data.items()):
+    for uniprot_accession, entries in sorted(data.items()):
         for e in sorted(entries, key=lambda x: (x.id, x.method)):
             writer.writerow(
                 {
-                    "uniprot_acc": uniprot_acc,
+                    "uniprot_accession": uniprot_accession,
                     "pdb_id": e.id,
                     "method": e.method,
                     "resolution": e.resolution or "",
                     "uniprot_chains": e.uniprot_chains,
                     "chain": e.chain,
+                    "chain_length": e.chain_length,
                 }
             )
 
 
 def _write_dict_of_sets2csv(file: TextIOWrapper, data: dict[str, set[str]], ref_id_field: str):
     _make_sure_parent_exists(file)
-    fieldnames = ["uniprot_acc", ref_id_field]
+    fieldnames = ["uniprot_accession", ref_id_field]
 
     writer = csv.DictWriter(file, fieldnames=fieldnames)
     writer.writeheader()
-    for uniprot_acc, ref_ids in sorted(data.items()):
+    for uniprot_accession, ref_ids in sorted(data.items()):
         for ref_id in sorted(ref_ids):
-            writer.writerow({"uniprot_acc": uniprot_acc, ref_id_field: ref_id})
+            writer.writerow({"uniprot_accession": uniprot_accession, ref_id_field: ref_id})
 
 
 def _iter_csv_rows(file: TextIOWrapper) -> Generator[dict[str, str]]:
@@ -1148,6 +1333,21 @@ def _write_complexes_csv(complexes: list[ComplexPortalEntry], output_csv: TextIO
         )
 
 
+def _write_uniprot_details_csv(
+    output_csv: TextIOWrapper,
+    uniprot_details_list: Iterable[UniprotDetails],
+) -> None:
+    if not uniprot_details_list:
+        msg = "No UniProt entries found for given accessions"
+        raise ValueError(msg)
+    # As all props of UniprotDetails are scalar, we can directly unstructure to dicts
+    rows = converter.unstructure(uniprot_details_list)
+    fieldnames = rows[0].keys()
+    writer = csv.DictWriter(output_csv, fieldnames=fieldnames)
+    writer.writeheader()
+    writer.writerows(rows)
+
+
 HANDLERS: dict[tuple[str, str | None], Callable] = {
     ("search", "uniprot"): _handle_search_uniprot,
     ("search", "pdbe"): _handle_search_pdbe,
@@ -1157,6 +1357,7 @@ HANDLERS: dict[tuple[str, str | None], Callable] = {
     ("search", "taxonomy"): _handle_search_taxonomy,
     ("search", "interaction-partners"): _handle_search_interaction_partners,
     ("search", "complexes"): _handle_search_complexes,
+    ("search", "uniprot-details"): _handle_search_uniprot_details,
     ("retrieve", "pdbe"): _handle_retrieve_pdbe,
     ("retrieve", "alphafold"): _handle_retrieve_alphafold,
     ("retrieve", "emdb"): _handle_retrieve_emdb,
@@ -1165,15 +1366,20 @@ HANDLERS: dict[tuple[str, str | None], Callable] = {
     ("filter", "residue"): _handle_filter_residue,
     ("filter", "secondary-structure"): _handle_filter_ss,
     ("mcp", None): _handle_mcp,
-    ("convert", None): _handle_convert,
+    ("convert", "structures"): _handle_convert_structures,
+    ("convert", "uniprot"): _handle_convert_uniprot,
 }
 
 
-def main():
-    """Main entry point for the CLI."""
+def main(argv: Sequence[str] | None = None):
+    """Main entry point for the CLI.
+
+    Args:
+        argv: List of command line arguments. If None, uses sys.argv.
+    """
     parser = make_parser()
-    args = parser.parse_args()
-    logging.basicConfig(level=args.log_level, handlers=[RichHandler(show_level=False)])
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=args.log_level, handlers=[RichHandler(show_level=False, console=console)])
 
     # Dispatch table to reduce complexity
     cmd = args.command