Metadata-Version: 2.4
Name: oeis-tools
Version: 0.2.0
Summary: A Python toolkit for programmatic access, analysis, and visualization of integer sequences from the OEIS (Online Encyclopedia of Integer Sequences).
Author-email: Enrique Pérez Herrero <energycode.org@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Enrique Pérez Herrero
        
        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.
        
Project-URL: Homepage, https://github.com/oeistools/oeis-tools
Project-URL: Repository, https://github.com/oeistools/oeis-tools
Project-URL: Issues, https://github.com/oeistools/oeis-tools/issues
Project-URL: Documentation, https://github.com/oeistools/oeis-tools#readme
Keywords: oeis,integer-sequences,number-theory,math
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Dynamic: license-file

# oeis-tools

[![CI](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/oeistools/oeis-tools/graph/badge.svg?token=VS85S5ZKYO)](https://codecov.io/gh/oeistools/oeis-tools)
[![PyPI version](https://img.shields.io/pypi/v/oeis-tools.svg?cacheSeconds=60)](https://pypi.org/project/oeis-tools/)
[![Python versions](https://img.shields.io/pypi/pyversions/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
[![Wheel](https://img.shields.io/pypi/wheel/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
[![Package format](https://img.shields.io/pypi/format/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A focused Python toolkit for working with OEIS integer sequences: fetch metadata, parse b-files, and plot sequence values quickly.

## Features

- Validate OEIS IDs like `A000045`
- Build canonical OEIS URLs and b-file names
- Fetch sequence JSON metadata via `Sequence`
- Fetch and parse b-file numeric data via `BFile`
- Plot b-file values with line or scatter styles

## Requirements

- Python 3.9+
- Optional: `matplotlib` for plotting

## Installation

```bash
pip install oeis-tools
```

For local development:

```bash
git clone https://github.com/oeistools/oeis-tools.git
cd oeis-tools
pip install -e ".[dev]"
```

## Quick Start

### Utility Functions

```python
import oeis_tools as ot

print(ot.check_id("A000045"))                # True
print(ot.oeis_bfile("A000045"))              # b000045.txt
print(ot.oeis_url("A000045"))                # https://oeis.org/A000045
print(ot.oeis_url("A000045", fmt="json"))    # https://oeis.org/search?q=id:A000045&fmt=json
```

### Sequence API

```python
from oeis_tools import Sequence

seq = Sequence("A000045")

print(seq.id)         # A000045
print(seq.name)       # Fibonacci numbers
print(seq.data)       # [0, 1, 1, 2, 3, 5, ...]
print(seq.author)     # list[str]
print(seq.keyword)    # list[str]
print(seq.offset)     # list[int]
print(seq.link)       # parsed links as markdown-style text

info = seq.get_bfile_info()
print(info["available"], info["length"])
```

### B-file API

```python
from oeis_tools import BFile

bfile = BFile("A000045")

print(bfile.get_filename())   # b000045.txt
print(bfile.get_url())        # https://oeis.org/A000045/b000045.txt
print(bfile.get_bfile_data()) # list[int] or None
bfile.plot_data(50, show=False)                                # first 50 points
bfile.plot_data(50, show=False, plot_style="scatter")          # scatter plot
bfile.plot_data(50, show=False, plot_style="joined")           # joined/line plot
ax = bfile.plot_data(show=False, return_ax=True)               # matplotlib Axes
```

## Plotting Examples

Overlay two sequences on one plot:

```python
import matplotlib.pyplot as plt
import oeis_tools

N_POINTS = 200

bfile = oeis_tools.BFile("A114906")
bfile2 = oeis_tools.BFile("A114904")
fig, ax = plt.subplots()
bfile.plot_data(n=N_POINTS, ax=ax, show=False, color="red")
bfile2.plot_data(n=N_POINTS, ax=ax, show=True, color="blue")
plt.show()
```

Scatter versus joined:

```python
import matplotlib.pyplot as plt
from oeis_tools import BFile

bfile = BFile("A000045")
fig, ax = plt.subplots()
bfile.plot_data(80, ax=ax, show=False, plot_style="scatter", color="black")
bfile.plot_data(80, ax=ax, show=False, plot_style="joined", color="orange")
plt.show()
```

## API Summary

- `check_id(oeis_id: str) -> bool`
- `oeis_bfile(oeis_id: str) -> str`
- `oeis_url(oeis_id: str, fmt: str | None = None) -> str`
- `Sequence(oeis_id: str)`
- `Sequence.get_bfile_info() -> dict`
- `BFile(oeis_id: str)`
- `BFile.get_filename() -> str`
- `BFile.get_url() -> str`
- `BFile.get_bfile_data() -> list[int] | None`
- `BFile.plot_data(n: int | None = None, show: bool = True, ax=None, return_ax: bool = False, plot_style: str = "line", **plot_kwargs)`

## Error Behavior

- `Sequence(...)` raises `ValueError` for invalid IDs.
- `Sequence(...)` propagates HTTP errors from the OEIS JSON endpoint.
- `BFile.get_bfile_data()` returns `None` when a b-file cannot be fetched or parsed.

## Development

Run tests:

```bash
pytest -q
```

Run lint checks:

```bash
ruff format .
ruff check . --fix
```

Build distributions:

```bash
python -m build
python -m twine check dist/*
```

Contribution guide: see `CONTRIBUTING.md`.

## Publishing

This repository includes a GitHub Actions publish workflow at `.github/workflows/publish.yml`.

- Automatic publish trigger: GitHub Release `published`
- Manual publish trigger: `workflow_dispatch`
- Upload target: PyPI via trusted publishing (`id-token`)

## License

MIT. See `LICENSE`.
