fastatacular 0.1.0__tar.gz

fastatacular-0.1.0/.github/workflows/python-package.yml

@@ -0,0 +1,58 @@
+name: Python Package
+
+on:
+  push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Install dependencies
+        run: just install
+
+      - name: Lint
+        run: just lint
+
+      - name: Type check
+        run: uv run ty check src
+
+      - name: Test with coverage
+        run: just test-cov
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: tacular-omics/fastatacular
+          fail_ci_if_error: false
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: tacular-omics/fastatacular
+          files: junit.xml
+          fail_ci_if_error: false

fastatacular-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,32 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastatacular-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# 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
+*.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
+junit.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# uv
+.venv
+uv.lock
+
+# ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# editors
+.vscode/
+.idea/

fastatacular-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Garrett
+
+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.

fastatacular-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: fastatacular
+Version: 0.1.0
+Summary: A pure-Python library for reading and writing FASTA sequence files.
+Project-URL: Repository, https://github.com/tacular-omics/fastatacular
+Project-URL: Issues, https://github.com/tacular-omics/fastatacular/issues
+Author-email: Patrick Garrett <pgarrett@scripps.edu>
+Maintainer-email: Patrick Garrett <pgarrett@scripps.edu>
+License: MIT
+License-File: LICENSE
+Keywords: bioinformatics,fasta,genomics,proteomics,sequence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# fastatacular
+
+[![Python Package](https://github.com/tacular-omics/fastatacular/actions/workflows/python-package.yml/badge.svg)](https://github.com/tacular-omics/fastatacular/actions/workflows/python-package.yml)
+[![License](https://img.shields.io/github/license/tacular-omics/fastatacular)](LICENSE)
+
+Pure-Python library for reading and writing [FASTA](https://en.wikipedia.org/wiki/FASTA_format) sequence files, with optional parsing of UniProt-style description keys (`OS=`, `OX=`, `GN=`, `PE=`, `SV=`) and pipe-delimited identifiers (`sp|P12345|EX_HUMAN`, `gi|12345|ref|NP_000001.1|`).
+
+It's the plain-FASTA companion to [pefftacular](https://github.com/tacular-omics/pefftacular) and ships with the same `read_*` / `*Reader` / `write_*` shape.
+
+## Install
+
+```bash
+pip install fastatacular
+```
+
+Dev install:
+
+```bash
+just install
+```
+
+## Quick start
+
+**read_fasta** — load everything into memory at once:
+
+```python
+from fastatacular import read_fasta
+
+entries = read_fasta("proteins.fasta")
+for entry in entries:
+    print(entry.identifier, len(entry.sequence))
+```
+
+**FastaReader** — iterate lazily without loading the full file:
+
+```python
+from fastatacular import FastaReader
+
+with FastaReader("proteins.fasta") as reader:
+    for entry in reader:
+        process(entry)
+```
+
+## Data model
+
+Each entry is a `SequenceEntry`:
+
+| Field | Type | Description |
+|---|---|---|
+| `identifier` | `str` | Token immediately after `>` (e.g. `sp|P12345|EX_HUMAN`) |
+| `sequence` | `str` | Concatenated sequence with whitespace stripped |
+| `prefix` | `str \| None` | Database prefix (`sp`, `tr`, `gi`, ...) when the id is pipe-delimited |
+| `accession` | `str \| None` | First pipe field (e.g. `P12345`) |
+| `entry_name` | `str \| None` | Third pipe field on UniProt ids (e.g. `EX_HUMAN`) |
+| `description` | `str \| None` | Free text after the identifier |
+| `pname` | `str \| None` | Protein name (description text, minus `KEY=value` pairs) |
+| `gname` | `str \| None` | Gene name (`GN=`) |
+| `os_name` | `str \| None` | Organism name (`OS=`) |
+| `ncbi_tax_id` | `int \| None` | NCBI taxonomy ID (`OX=`) |
+| `pe` | `int \| None` | Protein existence level (`PE=`) |
+| `sv` | `int \| None` | Sequence version (`SV=`) |
+| `extra` | `dict[str, str]` | Any other `KEY=value` pairs found in the header |
+| `raw_header` | `str` | The original header line (without leading `>`) |
+
+## UniProt-style headers
+
+```python
+from fastatacular import read_fasta
+
+[entry] = read_fasta("one.fasta")
+# >sp|P12345|EX_HUMAN Example protein OS=Homo sapiens OX=9606 GN=EXMP PE=1 SV=2
+
+entry.prefix         # "sp"
+entry.accession      # "P12345"
+entry.entry_name     # "EX_HUMAN"
+entry.pname          # "Example protein"
+entry.os_name        # "Homo sapiens"
+entry.ncbi_tax_id    # 9606
+entry.gname          # "EXMP"
+entry.pe             # 1
+entry.sv             # 2
+```
+
+Non-standard `KEY=value` pairs are captured in `entry.extra`. Headers with no `KEY=value` tokens leave `description` and `pname` populated and `extra` empty.
+
+## Writing
+
+Construct entries and write them out:
+
+```python
+from fastatacular import SequenceEntry, write_fasta
+
+entries = [
+    SequenceEntry(
+        identifier="sp|P12345|EX_HUMAN",
+        sequence="MKTIIALSYIFCLVFA",
+        pname="Example protein",
+        os_name="Homo sapiens",
+        ncbi_tax_id=9606,
+        gname="EXMP",
+        pe=1,
+        sv=2,
+    ),
+]
+
+write_fasta(entries, "output.fasta")
+```
+
+`dest` accepts a path string, a `pathlib.Path`, or a text-mode file object.
+
+Sequence lines wrap at 60 characters by default. Override with `line_width=` (pass `0` to disable wrapping):
+
+```python
+write_fasta(entries, "output.fasta", line_width=80)
+write_fasta(entries, "single-line.fasta", line_width=0)
+```
+
+If `raw_header` is set on an entry (as it is on every entry produced by `read_fasta`), the writer round-trips it verbatim. Otherwise the header is rebuilt from the structured fields.
+
+## Error handling
+
+Parse errors raise `FastaParseError`:
+
+```python
+from fastatacular import FastaParseError, read_fasta
+
+try:
+    entries = read_fasta("malformed.fasta")
+except FastaParseError as e:
+    print(e.line)     # offending line number
+    print(e.context)  # surrounding line content
+```
+
+Write errors raise `FastaWriteError`.
+
+## Development
+
+```bash
+just install      # install dependencies
+just test         # run tests
+just test-v       # run tests (verbose)
+just cov          # run tests with coverage
+just lint         # ruff lint
+just format       # ruff format
+just check        # lint + type check + test
+just build        # build the package
+just clean        # remove cache files
+```
+
+## License
+
+[MIT](LICENSE)

fastatacular-0.1.0/README.md

@@ -0,0 +1,152 @@
+# fastatacular
+
+[![Python Package](https://github.com/tacular-omics/fastatacular/actions/workflows/python-package.yml/badge.svg)](https://github.com/tacular-omics/fastatacular/actions/workflows/python-package.yml)
+[![License](https://img.shields.io/github/license/tacular-omics/fastatacular)](LICENSE)
+
+Pure-Python library for reading and writing [FASTA](https://en.wikipedia.org/wiki/FASTA_format) sequence files, with optional parsing of UniProt-style description keys (`OS=`, `OX=`, `GN=`, `PE=`, `SV=`) and pipe-delimited identifiers (`sp|P12345|EX_HUMAN`, `gi|12345|ref|NP_000001.1|`).
+
+It's the plain-FASTA companion to [pefftacular](https://github.com/tacular-omics/pefftacular) and ships with the same `read_*` / `*Reader` / `write_*` shape.
+
+## Install
+
+```bash
+pip install fastatacular
+```
+
+Dev install:
+
+```bash
+just install
+```
+
+## Quick start
+
+**read_fasta** — load everything into memory at once:
+
+```python
+from fastatacular import read_fasta
+
+entries = read_fasta("proteins.fasta")
+for entry in entries:
+    print(entry.identifier, len(entry.sequence))
+```
+
+**FastaReader** — iterate lazily without loading the full file:
+
+```python
+from fastatacular import FastaReader
+
+with FastaReader("proteins.fasta") as reader:
+    for entry in reader:
+        process(entry)
+```
+
+## Data model
+
+Each entry is a `SequenceEntry`:
+
+| Field | Type | Description |
+|---|---|---|
+| `identifier` | `str` | Token immediately after `>` (e.g. `sp|P12345|EX_HUMAN`) |
+| `sequence` | `str` | Concatenated sequence with whitespace stripped |
+| `prefix` | `str \| None` | Database prefix (`sp`, `tr`, `gi`, ...) when the id is pipe-delimited |
+| `accession` | `str \| None` | First pipe field (e.g. `P12345`) |
+| `entry_name` | `str \| None` | Third pipe field on UniProt ids (e.g. `EX_HUMAN`) |
+| `description` | `str \| None` | Free text after the identifier |
+| `pname` | `str \| None` | Protein name (description text, minus `KEY=value` pairs) |
+| `gname` | `str \| None` | Gene name (`GN=`) |
+| `os_name` | `str \| None` | Organism name (`OS=`) |
+| `ncbi_tax_id` | `int \| None` | NCBI taxonomy ID (`OX=`) |
+| `pe` | `int \| None` | Protein existence level (`PE=`) |
+| `sv` | `int \| None` | Sequence version (`SV=`) |
+| `extra` | `dict[str, str]` | Any other `KEY=value` pairs found in the header |
+| `raw_header` | `str` | The original header line (without leading `>`) |
+
+## UniProt-style headers
+
+```python
+from fastatacular import read_fasta
+
+[entry] = read_fasta("one.fasta")
+# >sp|P12345|EX_HUMAN Example protein OS=Homo sapiens OX=9606 GN=EXMP PE=1 SV=2
+
+entry.prefix         # "sp"
+entry.accession      # "P12345"
+entry.entry_name     # "EX_HUMAN"
+entry.pname          # "Example protein"
+entry.os_name        # "Homo sapiens"
+entry.ncbi_tax_id    # 9606
+entry.gname          # "EXMP"
+entry.pe             # 1
+entry.sv             # 2
+```
+
+Non-standard `KEY=value` pairs are captured in `entry.extra`. Headers with no `KEY=value` tokens leave `description` and `pname` populated and `extra` empty.
+
+## Writing
+
+Construct entries and write them out:
+
+```python
+from fastatacular import SequenceEntry, write_fasta
+
+entries = [
+    SequenceEntry(
+        identifier="sp|P12345|EX_HUMAN",
+        sequence="MKTIIALSYIFCLVFA",
+        pname="Example protein",
+        os_name="Homo sapiens",
+        ncbi_tax_id=9606,
+        gname="EXMP",
+        pe=1,
+        sv=2,
+    ),
+]
+
+write_fasta(entries, "output.fasta")
+```
+
+`dest` accepts a path string, a `pathlib.Path`, or a text-mode file object.
+
+Sequence lines wrap at 60 characters by default. Override with `line_width=` (pass `0` to disable wrapping):
+
+```python
+write_fasta(entries, "output.fasta", line_width=80)
+write_fasta(entries, "single-line.fasta", line_width=0)
+```
+
+If `raw_header` is set on an entry (as it is on every entry produced by `read_fasta`), the writer round-trips it verbatim. Otherwise the header is rebuilt from the structured fields.
+
+## Error handling
+
+Parse errors raise `FastaParseError`:
+
+```python
+from fastatacular import FastaParseError, read_fasta
+
+try:
+    entries = read_fasta("malformed.fasta")
+except FastaParseError as e:
+    print(e.line)     # offending line number
+    print(e.context)  # surrounding line content
+```
+
+Write errors raise `FastaWriteError`.
+
+## Development
+
+```bash
+just install      # install dependencies
+just test         # run tests
+just test-v       # run tests (verbose)
+just cov          # run tests with coverage
+just lint         # ruff lint
+just format       # ruff format
+just check        # lint + type check + test
+just build        # build the package
+just clean        # remove cache files
+```
+
+## License
+
+[MIT](LICENSE)

fastatacular-0.1.0/justfile

@@ -0,0 +1,59 @@
+default: lint format check test
+
+# Install dependencies
+install:
+    uv sync
+
+# Run linting checks
+lint:
+    uv run ruff check src
+
+# Format code
+format:
+	uv run ruff check --select I --fix src
+	uv run ruff format src
+
+# Run ty type checker
+ty:
+    uv run ty check src
+
+# Run type checking
+check:
+    just lint
+    just ty
+    just test
+
+# Run tests
+test:
+    uv run pytest tests
+
+# Run tests with verbose output
+test-v:
+    uv run pytest tests -v
+
+# Run tests for a specific file
+test-file FILE:
+    uv run pytest {{FILE}} -v
+
+# Run tests with coverage (terminal)
+cov:
+    uv run pytest tests --cov=src/fastatacular --cov-report=term-missing
+
+# Run tests with coverage (XML for Codecov) + JUnit XML for test results
+test-cov:
+    uv run pytest tests --cov=src/fastatacular --cov-report=xml --junitxml=junit.xml -o junit_family=legacy
+
+# Remove cache and compiled files
+clean:
+    find . -type d -name __pycache__ -exec rm -rf {} +
+    find . -type d -name .pytest_cache -exec rm -rf {} +
+    find . -type d -name .ruff_cache -exec rm -rf {} +
+    find . -name "*.pyc" -delete
+
+# Build the package
+build:
+    uv build
+
+# Install dev dependencies (alias for install)
+dev:
+    uv sync

fastatacular-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "fastatacular"
+version = "0.1.0"
+description = "A pure-Python library for reading and writing FASTA sequence files."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+authors = [
+    { name = "Patrick Garrett", email = "pgarrett@scripps.edu" }
+]
+license = {text = "MIT"}
+keywords = ["fasta", "proteomics", "genomics", "bioinformatics", "sequence"]
+maintainers = [
+    { name = "Patrick Garrett", email = "pgarrett@scripps.edu" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/tacular-omics/fastatacular"
+Issues = "https://github.com/tacular-omics/fastatacular/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastatacular"]
+
+[tool.uv]
+package = true
+dev-dependencies = [
+    "pytest>=9.0.2",
+    "pytest-cov>=6.0",
+    "ruff>=0.14.11",
+    "ty>=0.0.11",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/fastatacular"]
+omit = ["*/__pycache__/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

fastatacular-0.1.0/src/fastatacular/__init__.py

@@ -0,0 +1,15 @@
+"""fastatacular — A pure-Python FASTA parsing and writing library."""
+
+from fastatacular._models import SequenceEntry
+from fastatacular._parser import FastaReader, read_fasta
+from fastatacular._writer import write_fasta
+from fastatacular.errors import FastaParseError, FastaWriteError
+
+__all__ = [
+    "FastaParseError",
+    "FastaReader",
+    "FastaWriteError",
+    "SequenceEntry",
+    "read_fasta",
+    "write_fasta",
+]

fastatacular-0.1.0/src/fastatacular/_models.py

@@ -0,0 +1,42 @@
+"""Frozen dataclass models for FASTA file structures."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class SequenceEntry:
+    """A single sequence entry in a FASTA file.
+
+    Always populated:
+        identifier:  the token immediately after ``>`` (before any whitespace).
+        sequence:    the concatenated sequence with whitespace stripped.
+
+    Parsed from common header conventions when available:
+        prefix / accession / entry_name:
+            From UniProt-style ``db|ACCESSION|ENTRY_NAME`` identifiers, or
+            NCBI-style ``db|ID|...`` identifiers.
+        description: free text after the identifier, before any ``KEY=value``.
+        pname:       protein name (the description text minus UniProt keys).
+        gname:       gene name (``GN=``).
+        os_name:     organism name (``OS=``).
+        ncbi_tax_id: NCBI taxonomy ID (``OX=``).
+        pe:          protein existence level (``PE=``).
+        sv:          sequence version (``SV=``).
+        extra:       any other ``KEY=value`` pairs found in the header.
+        raw_header:  the original header line text (without the leading ``>``).
+    """
+
+    identifier: str
+    sequence: str
+    prefix: str | None = None
+    accession: str | None = None
+    entry_name: str | None = None
+    description: str | None = None
+    pname: str | None = None
+    gname: str | None = None
+    os_name: str | None = None
+    ncbi_tax_id: int | None = None
+    pe: int | None = None
+    sv: int | None = None
+    extra: dict[str, str] = field(default_factory=dict)
+    raw_header: str = ""

fastatacular-0.1.0/src/fastatacular/_parser.py

@@ -0,0 +1,206 @@
+"""FASTA file parser — converts text into model objects."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import TracebackType
+from typing import IO
+
+from fastatacular._models import SequenceEntry
+from fastatacular.errors import FastaParseError
+
+# Matches ``KEY=value`` pairs in UniProt-style headers. Value runs up to the
+# next ``KEY=`` token or end-of-string, then trailing whitespace is trimmed.
+_KV_PATTERN = re.compile(r"(?P<key>[A-Za-z_][A-Za-z0-9_]*)=(?P<val>.*?)(?=\s+[A-Za-z_][A-Za-z0-9_]*=|$)")
+
+# UniProt FASTA identifier: ``db|ACCESSION|ENTRY_NAME`` (e.g. ``sp|P12345|EX_HUMAN``)
+_UNIPROT_ID = re.compile(r"^(?P<prefix>[A-Za-z0-9]+)\|(?P<accession>[^|]+)\|(?P<entry_name>[^|\s]+)$")
+
+# NCBI-ish ``db|ID`` or ``db|ID|...`` identifier — accept the leading two fields.
+_PIPE_ID = re.compile(r"^(?P<prefix>[A-Za-z0-9]+)\|(?P<accession>[^|\s]+)(?:\|.*)?$")
+
+
+@dataclass(slots=True)
+class _ParsedHeader:
+    """Mutable scratch space built up while parsing a description line."""
+
+    identifier: str
+    raw_header: str
+    prefix: str | None = None
+    accession: str | None = None
+    entry_name: str | None = None
+    description: str | None = None
+    pname: str | None = None
+    gname: str | None = None
+    os_name: str | None = None
+    ncbi_tax_id: int | None = None
+    pe: int | None = None
+    sv: int | None = None
+    extra: dict[str, str] = field(default_factory=dict)
+
+
+def _parse_header_line(line: str, line_no: int) -> _ParsedHeader:
+    """Parse a single header line into structured fields."""
+    if not line.startswith(">"):
+        raise FastaParseError("Header line must start with '>'", line=line_no, context=line)
+
+    raw = line[1:].rstrip("\r\n")
+    stripped = raw.strip()
+    if not stripped:
+        raise FastaParseError("Empty FASTA header", line=line_no, context=line)
+
+    identifier, _, rest = stripped.partition(" ")
+    rest = rest.strip()
+
+    header = _ParsedHeader(identifier=identifier, raw_header=raw)
+
+    if m := _UNIPROT_ID.match(identifier):
+        header.prefix = m["prefix"]
+        header.accession = m["accession"]
+        header.entry_name = m["entry_name"]
+    elif m := _PIPE_ID.match(identifier):
+        header.prefix = m["prefix"]
+        header.accession = m["accession"]
+
+    if not rest:
+        return header
+
+    first_match_start: int | None = None
+    for m in _KV_PATTERN.finditer(rest):
+        key = m["key"]
+        value = m["val"].strip()
+        if first_match_start is None:
+            first_match_start = m.start()
+        if key == "GN":
+            header.gname = value
+        elif key == "OS":
+            header.os_name = value
+        elif key == "OX":
+            try:
+                header.ncbi_tax_id = int(value)
+            except ValueError:
+                header.extra[key] = value
+        elif key == "PE":
+            try:
+                header.pe = int(value)
+            except ValueError:
+                header.extra[key] = value
+        elif key == "SV":
+            try:
+                header.sv = int(value)
+            except ValueError:
+                header.extra[key] = value
+        else:
+            header.extra[key] = value
+
+    header.description = rest
+    if first_match_start is None:
+        header.pname = rest
+    elif first_match_start > 0:
+        header.pname = rest[:first_match_start].rstrip() or None
+
+    return header
+
+
+def _build_entry(header: _ParsedHeader, seq_chunks: list[str], header_line_no: int) -> SequenceEntry:
+    sequence = "".join(chunk for chunk in seq_chunks if chunk)
+    if not sequence:
+        raise FastaParseError(
+            f"Entry {header.identifier!r} has no sequence data",
+            line=header_line_no,
+            context=header.raw_header,
+        )
+    return SequenceEntry(
+        identifier=header.identifier,
+        sequence=sequence,
+        prefix=header.prefix,
+        accession=header.accession,
+        entry_name=header.entry_name,
+        description=header.description,
+        pname=header.pname,
+        gname=header.gname,
+        os_name=header.os_name,
+        ncbi_tax_id=header.ncbi_tax_id,
+        pe=header.pe,
+        sv=header.sv,
+        extra=header.extra,
+        raw_header=header.raw_header,
+    )
+
+
+def _iter_entries(fh: IO[str]) -> Iterator[SequenceEntry]:
+    """Yield ``SequenceEntry`` objects from an open text-mode file."""
+    header: _ParsedHeader | None = None
+    seq_chunks: list[str] = []
+    header_line_no: int = 0
+
+    for line_no, line in enumerate(fh, start=1):
+        if not line or line[0] in ("\n", "\r"):
+            continue
+        if line.startswith(";"):
+            # Comment line (NCBI / legacy FASTA convention) — skip.
+            continue
+        if line.startswith(">"):
+            if header is not None:
+                yield _build_entry(header, seq_chunks, header_line_no)
+            header = _parse_header_line(line, line_no)
+            header_line_no = line_no
+            seq_chunks = []
+        else:
+            if header is None:
+                raise FastaParseError(
+                    "Sequence data appears before any '>' header",
+                    line=line_no,
+                    context=line.rstrip("\n"),
+                )
+            seq_chunks.append(line.strip())
+
+    if header is not None:
+        yield _build_entry(header, seq_chunks, header_line_no)
+
+
+class FastaReader:
+    """Iterate over a FASTA file lazily without loading the entire file."""
+
+    def __init__(self, source: str | Path | IO[str]) -> None:
+        self._source = source
+        self._fh: IO[str] | None = None
+        self._owns_fh = False
+
+    def __enter__(self) -> FastaReader:
+        if isinstance(self._source, (str, Path)):
+            self._fh = Path(self._source).open(encoding="utf-8")
+            self._owns_fh = True
+        else:
+            self._fh = self._source
+            self._owns_fh = False
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if self._owns_fh and self._fh is not None:
+            self._fh.close()
+        self._fh = None
+
+    def __iter__(self) -> Iterator[SequenceEntry]:
+        if self._fh is None:
+            raise RuntimeError("FastaReader must be used as a context manager (`with FastaReader(...) as r:`)")
+        return _iter_entries(self._fh)
+
+
+def read_fasta(source: str | Path | IO[str]) -> list[SequenceEntry]:
+    """Read an entire FASTA file into a list of ``SequenceEntry`` objects."""
+    if isinstance(source, (str, Path)):
+        with Path(source).open(encoding="utf-8") as fh:
+            return list(_iter_entries(fh))
+    return list(_iter_entries(source))
+
+
+__all__ = ["FastaReader", "read_fasta"]

fastatacular-0.1.0/src/fastatacular/_writer.py

@@ -0,0 +1,83 @@
+"""FASTA file writer — serializes models back to FASTA format."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import IO
+
+from fastatacular._models import SequenceEntry
+from fastatacular.errors import FastaWriteError
+
+_SEQ_LINE_WIDTH = 60
+
+
+def _build_header_line(entry: SequenceEntry) -> str:
+    """Reconstruct a FASTA description line for ``entry``.
+
+    Priority: if ``raw_header`` was preserved during parsing, round-trip it
+    exactly. Otherwise rebuild from the structured fields.
+    """
+    if entry.raw_header:
+        return f">{entry.raw_header}"
+
+    parts: list[str] = [entry.identifier]
+    if entry.pname:
+        parts.append(entry.pname)
+    elif entry.description:
+        parts.append(entry.description)
+
+    if entry.os_name is not None:
+        parts.append(f"OS={entry.os_name}")
+    if entry.ncbi_tax_id is not None:
+        parts.append(f"OX={entry.ncbi_tax_id}")
+    if entry.gname is not None:
+        parts.append(f"GN={entry.gname}")
+    if entry.pe is not None:
+        parts.append(f"PE={entry.pe}")
+    if entry.sv is not None:
+        parts.append(f"SV={entry.sv}")
+    for k, v in entry.extra.items():
+        parts.append(f"{k}={v}")
+
+    return ">" + " ".join(parts)
+
+
+def _write_entry(entry: SequenceEntry, out: IO[str], line_width: int) -> None:
+    if not entry.identifier:
+        raise FastaWriteError("SequenceEntry has an empty identifier")
+    if not entry.sequence:
+        raise FastaWriteError(f"SequenceEntry {entry.identifier!r} has an empty sequence")
+
+    out.write(_build_header_line(entry) + "\n")
+
+    seq = entry.sequence
+    if line_width <= 0:
+        out.write(seq + "\n")
+        return
+    for i in range(0, len(seq), line_width):
+        out.write(seq[i : i + line_width] + "\n")
+
+
+def write_fasta(
+    entries: Iterable[SequenceEntry],
+    dest: str | Path | IO[str],
+    *,
+    line_width: int = _SEQ_LINE_WIDTH,
+) -> None:
+    """Write a sequence of ``SequenceEntry`` objects to FASTA.
+
+    ``dest`` may be a path or an already-opened text-mode file object.
+    ``line_width`` controls sequence wrapping; pass ``0`` (or any value ``<= 0``)
+    to emit each sequence on a single line.
+    """
+    if isinstance(dest, (str, Path)):
+        with Path(dest).open("w", encoding="utf-8") as fh:
+            for entry in entries:
+                _write_entry(entry, fh, line_width)
+    else:
+        for entry in entries:
+            _write_entry(entry, dest, line_width)
+
+
+__all__ = ["write_fasta"]

fastatacular-0.1.0/src/fastatacular/errors.py

@@ -0,0 +1,14 @@
+"""FASTA-specific error types."""
+
+
+class FastaParseError(ValueError):
+    """Raised when FASTA input cannot be parsed."""
+
+    def __init__(self, message: str, *, line: int | None = None, context: str | None = None) -> None:
+        self.line = line
+        self.context = context
+        super().__init__(message if line is None else f"Line {line}: {message}")
+
+
+class FastaWriteError(ValueError):
+    """Raised when a model object cannot be serialized to FASTA."""

fastatacular-0.1.0/tests/test_basic.py

@@ -0,0 +1,19 @@
+"""Smoke test: verify public API is importable."""
+
+from fastatacular import (
+    FastaParseError,
+    FastaReader,
+    FastaWriteError,
+    SequenceEntry,
+    read_fasta,
+    write_fasta,
+)
+
+
+def test_public_api_importable():
+    assert FastaParseError is not None
+    assert FastaReader is not None
+    assert FastaWriteError is not None
+    assert SequenceEntry is not None
+    assert read_fasta is not None
+    assert write_fasta is not None

fastatacular-0.1.0/tests/test_reader.py

@@ -0,0 +1,114 @@
+"""Tests for the FASTA reader."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from fastatacular import FastaParseError, FastaReader, read_fasta
+
+
+def _read_str(text: str):
+    return read_fasta(io.StringIO(text))
+
+
+def test_plain_single_entry():
+    entries = _read_str(">myid simple description\nACDEFG\nHIJKLM\n")
+    assert len(entries) == 1
+    e = entries[0]
+    assert e.identifier == "myid"
+    assert e.sequence == "ACDEFGHIJKLM"
+    assert e.description == "simple description"
+    assert e.pname == "simple description"
+    assert e.prefix is None
+    assert e.accession is None
+    assert e.gname is None
+    assert e.extra == {}
+
+
+def test_multiple_entries():
+    text = ">a one\nAAA\n>b two\nCCC\nGGG\n>c three\nTTT\n"
+    entries = _read_str(text)
+    assert [e.identifier for e in entries] == ["a", "b", "c"]
+    assert [e.sequence for e in entries] == ["AAA", "CCCGGG", "TTT"]
+
+
+def test_uniprot_style_header():
+    header = ">sp|P12345|EX_HUMAN Example protein OS=Homo sapiens OX=9606 GN=EXMP PE=1 SV=2\nMKTIIALSYIFCLVFA\n"
+    [e] = _read_str(header)
+    assert e.prefix == "sp"
+    assert e.accession == "P12345"
+    assert e.entry_name == "EX_HUMAN"
+    assert e.pname == "Example protein"
+    assert e.os_name == "Homo sapiens"
+    assert e.ncbi_tax_id == 9606
+    assert e.gname == "EXMP"
+    assert e.pe == 1
+    assert e.sv == 2
+    assert e.sequence == "MKTIIALSYIFCLVFA"
+
+
+def test_ncbi_style_pipe_id():
+    [e] = _read_str(">gi|12345|ref|NP_000001.1| some description\nACDEFG\n")
+    assert e.identifier == "gi|12345|ref|NP_000001.1|"
+    assert e.prefix == "gi"
+    assert e.accession == "12345"
+    assert e.entry_name is None
+    assert e.description == "some description"
+
+
+def test_extra_keys_captured():
+    [e] = _read_str(">id name part FOO=bar BAZ=qux extra trailing\nA\n")
+    assert e.extra == {"FOO": "bar", "BAZ": "qux extra trailing"}
+    assert e.pname == "name part"
+
+
+def test_skips_blank_and_comment_lines():
+    text = "\n; this is a comment\n>id description\nACDE\n\nFGHI\n"
+    [e] = _read_str(text)
+    assert e.sequence == "ACDEFGHI"
+
+
+def test_sequence_before_header_raises():
+    with pytest.raises(FastaParseError) as exc:
+        _read_str("ACDEFG\n>id description\nACDE\n")
+    assert exc.value.line == 1
+
+
+def test_empty_sequence_raises():
+    with pytest.raises(FastaParseError):
+        _read_str(">id description\n>next other\nACDE\n")
+
+
+def test_empty_header_raises():
+    with pytest.raises(FastaParseError):
+        _read_str("> \nACDE\n")
+
+
+def test_lazy_reader_context_manager(tmp_path):
+    p = tmp_path / "x.fasta"
+    p.write_text(">a x\nAAA\n>b y\nCCC\n")
+    with FastaReader(p) as reader:
+        ids = [e.identifier for e in reader]
+    assert ids == ["a", "b"]
+
+
+def test_lazy_reader_requires_context_manager():
+    reader = FastaReader(io.StringIO(">a x\nAAA\n"))
+    with pytest.raises(RuntimeError):
+        next(iter(reader))
+
+
+def test_header_with_no_description():
+    [e] = _read_str(">justanid\nACDE\n")
+    assert e.identifier == "justanid"
+    assert e.description is None
+    assert e.pname is None
+    assert e.sequence == "ACDE"
+
+
+def test_invalid_ox_falls_back_to_extra():
+    [e] = _read_str(">id name OX=notanumber\nACDE\n")
+    assert e.ncbi_tax_id is None
+    assert e.extra == {"OX": "notanumber"}

fastatacular-0.1.0/tests/test_roundtrip.py

@@ -0,0 +1,43 @@
+"""Round-trip tests: parse then re-emit."""
+
+from __future__ import annotations
+
+import io
+
+from fastatacular import read_fasta, write_fasta
+
+
+def test_roundtrip_preserves_sequences_and_ids():
+    src = (
+        ">sp|P12345|EX_HUMAN Example protein OS=Homo sapiens OX=9606 GN=EXMP PE=1 SV=2\n"
+        "MKTIIALSYIFCLVFA\n"
+        "ACDEFGHIKLMNPQRS\n"
+        ">tr|Q99999|UNK Second entry OS=Mus musculus OX=10090\n"
+        "MAGICSEQ\n"
+    )
+    entries = read_fasta(io.StringIO(src))
+    buf = io.StringIO()
+    write_fasta(entries, buf)
+    rebuilt = read_fasta(io.StringIO(buf.getvalue()))
+
+    assert len(rebuilt) == len(entries) == 2
+    for original, after in zip(entries, rebuilt, strict=True):
+        assert original.identifier == after.identifier
+        assert original.sequence == after.sequence
+        assert original.accession == after.accession
+        assert original.gname == after.gname
+        assert original.ncbi_tax_id == after.ncbi_tax_id
+        assert original.pe == after.pe
+        assert original.sv == after.sv
+
+
+def test_roundtrip_via_file(tmp_path):
+    src = ">id desc\nACDEFG\n>other thing\nHHHH\n"
+    entries = read_fasta(io.StringIO(src))
+
+    p = tmp_path / "out.fasta"
+    write_fasta(entries, p)
+
+    rebuilt = read_fasta(p)
+    assert [e.identifier for e in rebuilt] == ["id", "other"]
+    assert [e.sequence for e in rebuilt] == ["ACDEFG", "HHHH"]

fastatacular-0.1.0/tests/test_writer.py

@@ -0,0 +1,90 @@
+"""Tests for the FASTA writer."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from fastatacular import FastaWriteError, SequenceEntry, write_fasta
+
+
+def _write_str(entries, **kw) -> str:
+    buf = io.StringIO()
+    write_fasta(entries, buf, **kw)
+    return buf.getvalue()
+
+
+def test_write_minimal_entry():
+    entry = SequenceEntry(identifier="foo", sequence="ACDEFG")
+    out = _write_str([entry])
+    assert out == ">foo\nACDEFG\n"
+
+
+def test_write_with_pname_and_keys():
+    entry = SequenceEntry(
+        identifier="sp|P12345|EX_HUMAN",
+        sequence="MKTIIALSYIFCLVFA",
+        pname="Example protein",
+        os_name="Homo sapiens",
+        ncbi_tax_id=9606,
+        gname="EXMP",
+        pe=1,
+        sv=2,
+    )
+    out = _write_str([entry])
+    assert out.startswith(">sp|P12345|EX_HUMAN Example protein OS=Homo sapiens OX=9606 GN=EXMP PE=1 SV=2\n")
+    assert "MKTIIALSYIFCLVFA\n" in out
+
+
+def test_write_wraps_at_line_width():
+    entry = SequenceEntry(identifier="x", sequence="A" * 130)
+    out = _write_str([entry])
+    seq_lines = out.splitlines()[1:]
+    assert all(len(line) <= 60 for line in seq_lines)
+    assert sum(len(line) for line in seq_lines) == 130
+
+
+def test_write_custom_line_width():
+    entry = SequenceEntry(identifier="x", sequence="ACDEFGHIJK")
+    out = _write_str([entry], line_width=4)
+    assert out == ">x\nACDE\nFGHI\nJK\n"
+
+
+def test_write_no_wrap_when_line_width_zero():
+    entry = SequenceEntry(identifier="x", sequence="A" * 200)
+    out = _write_str([entry], line_width=0)
+    assert out == ">x\n" + "A" * 200 + "\n"
+
+
+def test_raw_header_round_trips_exactly():
+    entry = SequenceEntry(
+        identifier="anything",
+        sequence="AAA",
+        raw_header="sp|P00001|FOO Original header text OS=Mus OX=10090",
+    )
+    out = _write_str([entry])
+    assert out.startswith(">sp|P00001|FOO Original header text OS=Mus OX=10090\n")
+
+
+def test_write_empty_identifier_raises():
+    entry = SequenceEntry(identifier="", sequence="A")
+    with pytest.raises(FastaWriteError):
+        _write_str([entry])
+
+
+def test_write_empty_sequence_raises():
+    entry = SequenceEntry(identifier="x", sequence="")
+    with pytest.raises(FastaWriteError):
+        _write_str([entry])
+
+
+def test_extra_keys_are_emitted():
+    entry = SequenceEntry(
+        identifier="x",
+        sequence="A",
+        pname="name",
+        extra={"FOO": "bar"},
+    )
+    out = _write_str([entry])
+    assert out.startswith(">x name FOO=bar\n")