oeis-tools 0.1.0__tar.gz

oeis_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

oeis_tools-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include tests *
+global-exclude __pycache__ *.py[cod]

oeis_tools-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: oeis-tools
+Version: 0.1.0
+Summary: Tools and utilities for working with OEIS integer sequences
+Author-email: Enrique Pérez Herrero <energycode.org@gmail.com>
+License-Expression: MIT
+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
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Dynamic: license-file
+
+# oeis-tools
+
+[![Tests](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml/badge.svg)](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`oeis-tools` is a Python package for working with the
+[Online Encyclopedia of Integer Sequences (OEIS)](https://oeis.org/).
+
+It provides:
+- OEIS ID validation
+- URL and b-file helpers
+- A `Sequence` class for OEIS JSON entries
+- A `BFile` class for b-file numeric data
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install oeis-tools
+```
+
+From source:
+
+```bash
+git clone https://github.com/oeistools/oeis-tools.git
+cd oeis-tools
+pip install -e .
+```
+
+Development dependencies (tests):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import oeis_tools
+
+# Utilities
+print(oeis_tools.check_id("A000001"))              # True
+print(oeis_tools.oeis_bfile("A000001"))            # b000001.txt
+print(oeis_tools.oeis_url("A000001", fmt="json"))  # https://oeis.org/search?q=id:A000001&fmt=json
+
+# Sequence API
+seq = oeis_tools.Sequence("A000045")
+print(seq.name)        # Fibonacci numbers
+print(seq.data)        # comma-separated terms
+print(seq.author)      # list[str]
+print(seq.json["id"])  # raw JSON field access
+
+# B-file API
+bfile = oeis_tools.BFile("A000045")
+print(bfile.get_filename())      # b000045.txt
+print(bfile.get_url())           # https://oeis.org/A000045/b000045.txt
+print(bfile.get_bfile_data()[:5])
+```
+
+## API Overview
+
+- `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)`
+  - Key attributes: `id`, `json`, `name`, `data`, `author`, `link`, `bfile`
+- `BFile(oeis_id: str)`
+  - Methods: `get_filename()`, `get_url()`, `get_bfile_data()`
+
+## Running Tests
+
+```bash
+pytest -q
+```
+
+## License
+
+MIT. See `LICENSE`.
+
+## Author
+
+Enrique Pérez Herrero - [energycode.org@gmail.com](mailto:energycode.org@gmail.com)

oeis_tools-0.1.0/README.md

@@ -0,0 +1,84 @@
+# oeis-tools
+
+[![Tests](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml/badge.svg)](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`oeis-tools` is a Python package for working with the
+[Online Encyclopedia of Integer Sequences (OEIS)](https://oeis.org/).
+
+It provides:
+- OEIS ID validation
+- URL and b-file helpers
+- A `Sequence` class for OEIS JSON entries
+- A `BFile` class for b-file numeric data
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install oeis-tools
+```
+
+From source:
+
+```bash
+git clone https://github.com/oeistools/oeis-tools.git
+cd oeis-tools
+pip install -e .
+```
+
+Development dependencies (tests):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import oeis_tools
+
+# Utilities
+print(oeis_tools.check_id("A000001"))              # True
+print(oeis_tools.oeis_bfile("A000001"))            # b000001.txt
+print(oeis_tools.oeis_url("A000001", fmt="json"))  # https://oeis.org/search?q=id:A000001&fmt=json
+
+# Sequence API
+seq = oeis_tools.Sequence("A000045")
+print(seq.name)        # Fibonacci numbers
+print(seq.data)        # comma-separated terms
+print(seq.author)      # list[str]
+print(seq.json["id"])  # raw JSON field access
+
+# B-file API
+bfile = oeis_tools.BFile("A000045")
+print(bfile.get_filename())      # b000045.txt
+print(bfile.get_url())           # https://oeis.org/A000045/b000045.txt
+print(bfile.get_bfile_data()[:5])
+```
+
+## API Overview
+
+- `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)`
+  - Key attributes: `id`, `json`, `name`, `data`, `author`, `link`, `bfile`
+- `BFile(oeis_id: str)`
+  - Methods: `get_filename()`, `get_url()`, `get_bfile_data()`
+
+## Running Tests
+
+```bash
+pytest -q
+```
+
+## License
+
+MIT. See `LICENSE`.
+
+## Author
+
+Enrique Pérez Herrero - [energycode.org@gmail.com](mailto:energycode.org@gmail.com)

oeis_tools-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oeis-tools"
+dynamic = ["version"]
+description = "Tools and utilities for working with OEIS integer sequences"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Enrique Pérez Herrero", email = "energycode.org@gmail.com" }
+]
+
+keywords = [
+  "oeis",
+  "integer-sequences",
+  "number-theory",
+  "math"
+]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12"
+]
+
+dependencies = [
+  "requests>=2.31"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4"
+]
+
+[project.urls]
+Homepage = "https://github.com/oeistools/oeis-tools"
+Repository = "https://github.com/oeistools/oeis-tools"
+Issues = "https://github.com/oeistools/oeis-tools/issues"
+Documentation = "https://github.com/oeistools/oeis-tools#readme"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.dynamic]
+version = {attr = "oeis_tools.__version__.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

oeis_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oeis_tools-0.1.0/src/oeis_tools/__init__.py

@@ -0,0 +1,34 @@
+"""
+oeis_tools: A Python package for reading and manipulating data from OEIS.org.
+
+This package provides an object-oriented interface to fetch, parse, and work with
+integer sequences from the Online Encyclopedia of Integer Sequences (OEIS).
+It follows PEP 8 style guidelines and emphasizes OOP principles for extensibility.
+
+Key components:
+- Sequence: Core class for representing and interacting with OEIS sequences.
+
+Example usage:
+    from oeis_tools import Sequence
+
+    seq = Sequence.from_id('A000045')  # Fetch Fibonacci sequence
+    print(seq.terms[:12])  # Output first 12 terms
+
+For more details, refer to the documentation in individual modules.
+"""
+
+from .__version__ import __version__
+from .utils import check_id, oeis_bfile, oeis_url
+from .utils import OEIS_URL
+from .bfile import BFile
+from .sequence import Sequence
+
+__all__ = [
+    "__version__",
+    "check_id",
+    "oeis_bfile",
+    "oeis_url",
+    "OEIS_URL",
+    "BFile",
+    "Sequence",
+]

oeis_tools-0.1.0/src/oeis_tools/__version__.py

@@ -0,0 +1,8 @@
+"""
+Version information for oeis_tools package.
+
+This module defines the package version following PEP 8 conventions.
+It can be imported in __init__.py for easy access to the version string.
+"""
+
+__version__ = "0.1.0"

oeis_tools-0.1.0/src/oeis_tools/bfile.py

@@ -0,0 +1,98 @@
+"""
+Utilities for working with OEIS b-files.
+
+This module provides the BFile class, which represents an OEIS b-file
+associated with an integer sequence. A b-file contains sequence values
+in the format "n a(n)", one pair per line.
+
+The BFile class handles:
+- construction of b-file filenames and URLs
+- downloading b-files from the OEIS website
+- parsing numeric sequence data
+
+Typical usage:
+    >>> from oeis_tools.bfile import BFile
+    >>> bfile = BFile("A000045")
+    >>> bfile.get_bfile_data()
+"""
+
+import requests
+from .utils import oeis_bfile, oeis_url
+
+
+class BFile:
+    """
+    Represents an OEIS b-file and provides access to its numeric data.
+
+    A b-file contains values of an integer sequence in the form:
+    n a(n), one pair per line. This class fetches the b-file from
+    the OEIS website and parses its contents into a list of integers.
+
+    Attributes:
+        oeis_id (str): The OEIS identifier (e.g., 'A000045').
+        filename (str): The b-file name (e.g., 'bA000045.txt').
+        url (str): The URL where the b-file can be downloaded.
+        bfile_data (list[int] or None): Parsed sequence values from the
+            b-file, or None if the b-file could not be retrieved or parsed.
+    """
+
+    def __init__(self, oeis_id):
+        self.oeis_id = oeis_id
+        self.filename = oeis_bfile(oeis_id)
+        self.url = oeis_url(oeis_id, fmt="bfile")
+        self.data = self.fetch_bfile_data()
+
+    def fetch_bfile_data(self):
+        """
+        Fetch and parse the b-file into a list of integers.
+
+        Returns:
+            list[int] or None: Parsed sequence values, or None on failure.
+        """
+        try:
+            response = requests.get(self.url, timeout=10)
+            response.raise_for_status()
+        except requests.RequestException:
+            return None
+
+        data = []
+        for line in response.text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            try:
+                # format: n a(n)
+                _, value = line.split()
+                data.append(int(value))
+            except (ValueError, IndexError):
+                return None
+
+        return data
+
+    def get_filename(self):
+        """
+        Return the local filename of the OEIS b-file.
+
+        Returns:
+            str: The b-file filename (e.g., 'bA000045.txt').
+        """
+        return self.filename
+
+    def get_url(self):
+        """
+        Return the URL of the OEIS b-file.
+
+        Returns:
+            str: The full URL pointing to the b-file on oeis.org.
+        """
+        return self.url
+
+    def get_bfile_data(self):
+        """
+        Return the numeric data parsed from the OEIS b-file.
+
+        Returns:
+            list[int] or None: A list of sequence values extracted from the
+            b-file, or None if the b-file could not be fetched or parsed.
+        """
+        return self.data

oeis_tools-0.1.0/src/oeis_tools/sequence.py

@@ -0,0 +1,265 @@
+"""Tools and utilities for working with OEIS integer sequences."""
+
+import re
+from datetime import datetime
+import requests
+
+from .__version__ import __version__
+from .utils import check_id, oeis_bfile, oeis_url, OEIS_URL
+from .bfile import BFile
+
+class Sequence:
+    """
+    A class to represent an OEIS sequence, fetching data from the JSON API.
+    
+    Attributes:
+        id (str): The OEIS ID.
+        json (dict): The JSON data fetched from OEIS for the sequence.
+        m_id (str or None): The M ID from the 'id' field (e.g., 'M0692'), or None.
+        n_id (str or None): The N ID from the 'id' field (e.g., 'N0256'), or None.
+        time (datetime or None): The last modification time from the 'time' field.
+        created (datetime or None): The creation time from the 'created' field.
+        link (str): Formatted links from the 'link' field as printable text with hyperlinks.
+        BFile (BFile or None): The BFile object if available, else None.
+        data (str): The sequence data from the 'data' field.
+        name (str): The sequence name from the 'name' field.
+        comment (str): Comments from the 'comment' field.
+        reference (str): References from the 'reference' field.
+        formula (str): Formulas from the 'formula' field.
+        example (str): Examples from the 'example' field.
+        maple (str): Maple code from the 'maple' field.
+        mathematica (str): Mathematica code from the 'mathematica' field.
+        program (str): Programs from the 'program' field.
+        xref (str): Cross-references from the 'xref' field.
+        keyword (list[str]): Keywords parsed from the 'keyword' field.
+        offset (list[int]): Offset values parsed from the 'offset' field.
+        author (list[str]): Author names parsed from the 'author' field.
+        references (str): Additional references from the 'references' field.
+        revision (str): Revision information from the 'revision' field.
+    """
+
+    def __init__(self, oeis_id):
+        """
+        Initialize the Sequence with the given OEIS ID.
+        
+        Args:
+            oeis_id (str): The OEIS ID, e.g., 'A000001'.
+        
+        Raises:
+            ValueError: If the oeis_id is invalid.
+            requests.HTTPError: If the request fails.
+        """
+        if not check_id(oeis_id):
+            raise ValueError(f"Invalid OEIS ID: {oeis_id}")
+
+        json_url = oeis_url(oeis_id, fmt="json")
+        response = requests.get(json_url, timeout=10)
+        response.raise_for_status()
+        self.json = response.json()[0]
+        self.id = oeis_id
+
+        # Add direct attributes from json
+        self.data = self.json.get('data', '')
+        self.name = self.json.get('name', '')
+        comment_raw = self.json.get('comment', [])
+        self.comment = ('\n'.join(comment_raw) if isinstance(comment_raw, list)
+                       else comment_raw)
+        reference_raw = self.json.get('reference', [])
+        self.reference = ('\n'.join(reference_raw) if isinstance(reference_raw, list)
+                         else reference_raw)
+        formula_raw = self.json.get('formula', [])
+        self.formula = ('\n'.join(formula_raw) if isinstance(formula_raw, list)
+                       else formula_raw)
+        example_raw = self.json.get('example', [])
+        self.example = ('\n'.join(example_raw) if isinstance(example_raw, list)
+                       else example_raw)
+        maple_raw = self.json.get('maple', [])
+        self.maple = ('\n'.join(maple_raw) if isinstance(maple_raw, list)
+                     else maple_raw)
+        mathematica_raw = self.json.get('mathematica', [])
+        self.mathematica = ('\n'.join(mathematica_raw) if isinstance(mathematica_raw, list)
+                           else mathematica_raw)
+        program_raw = self.json.get('program', [])
+        self.program = ('\n'.join(program_raw) if isinstance(program_raw, list)
+                       else program_raw)
+        xref_raw = self.json.get('xref', [])
+        self.xref = ('\n'.join(xref_raw) if isinstance(xref_raw, list)
+                    else xref_raw)
+        self.keyword = self._parse_keywords(self.json.get('keyword', ''))
+        self.offset = self._parse_offset(self.json.get('offset', ''))
+        self.author = self._parse_authors(self.json.get('author', ''))
+        references_raw = self.json.get('references', [])
+        self.references = ('\n'.join(references_raw) if isinstance(references_raw, list)
+                          else references_raw)
+        self.revision = self.json.get('revision', '')
+
+        # Parse M and N IDs from the 'id' field
+        id_str = self.json.get('id', '')
+        parts = id_str.split() if id_str else []
+        self.m_id = parts[0] if parts else None
+        self.n_id = parts[1] if len(parts) > 1 else None
+
+        # Parse time and created as datetime objects
+        time_str = self.json.get('time')
+        self.time = datetime.fromisoformat(time_str) if time_str else None
+        created_str = self.json.get('created')
+        self.created = datetime.fromisoformat(created_str) if created_str else None
+
+        # Parse links as formatted text with hyperlinks
+        links = self.json.get('link', [])
+        formatted_links = []
+        for link in links:
+            # Parse HTML <a href="url">text</a> and convert to Markdown [text](url)
+            match = re.search(r'<a href="([^"]*)">(.*?)</a>', link)
+            if match:
+                url, text = match.groups()
+                if url.startswith('/'):
+                    url = OEIS_URL + url
+                formatted_links.append(f"[{text}]({url})")
+            else:
+                # If no <a>, just add the text, but replace relative URLs
+                formatted_link = re.sub(r'href="/', f'href="{OEIS_URL}/', link)
+                formatted_links.append(formatted_link)
+        self.link = '\n'.join(formatted_links) if formatted_links else ''
+
+        # Fetch BFile if content if b-file link is present
+        self.bfile = BFile(self.id)
+
+    def get_bfile_info(self):
+        """
+        Return summary information about the attached b-file data.
+
+        Returns:
+            dict: Metadata and basic stats for b-file values.
+        """
+        data = self.bfile.get_bfile_data() if self.bfile else None
+        if data is None:
+            return {
+                "available": False,
+                "filename": self.bfile.get_filename() if self.bfile else None,
+                "url": self.bfile.get_url() if self.bfile else None,
+                "length": 0,
+                "first": None,
+                "last": None,
+                "min": None,
+                "max": None,
+            }
+
+        return {
+            "available": True,
+            "filename": self.bfile.get_filename(),
+            "url": self.bfile.get_url(),
+            "length": len(data),
+            "first": data[0] if data else None,
+            "last": data[-1] if data else None,
+            "min": min(data) if data else None,
+            "max": max(data) if data else None,
+        }
+
+    @staticmethod
+    def _parse_authors(author_raw):
+        """
+        Parse OEIS author field into a clean list of author names.
+
+        The OEIS author field may include markdown-like underscores for
+        emphasis (e.g. ``_Tom Verhoeff_, _N. J. A. Sloane_``). This
+        method removes wrapper underscores and returns a list of names.
+
+        Args:
+            author_raw (str or list[str]): Raw author value from OEIS JSON.
+
+        Returns:
+            list[str]: Cleaned author names.
+        """
+        if isinstance(author_raw, list):
+            chunks = author_raw
+        elif isinstance(author_raw, str):
+            chunks = author_raw.split(",")
+        else:
+            return []
+
+        authors = []
+        for chunk in chunks:
+            name = chunk.strip()
+            name = re.sub(r'^_+|_+$', '', name).strip()
+            if Sequence._is_date_token(name):
+                continue
+            if name:
+                authors.append(name)
+        return authors
+
+    @staticmethod
+    def _is_date_token(value):
+        """
+        Return True when a token is a date-like value, not an author name.
+
+        Examples that should be filtered:
+        - ``1964``
+        - ``Apr 28 2012``
+        - ``Apr 28, 2012``
+        - ``2012-04-28``
+        """
+        if re.fullmatch(r"\d{4}", value):
+            return True
+
+        date_patterns = [
+            r"[A-Za-z]{3,9}\.? \d{1,2},? \d{4}",
+            r"\d{1,2} [A-Za-z]{3,9}\.? \d{4}",
+            r"\d{4}-\d{2}-\d{2}",
+        ]
+        return any(re.fullmatch(pattern, value) for pattern in date_patterns)
+
+    @staticmethod
+    def _parse_offset(offset_raw):
+        """
+        Parse OEIS offset field into a list of integers.
+
+        Typical OEIS values look like ``"0,2"`` and are returned as ``[0, 2]``.
+        """
+        if isinstance(offset_raw, list):
+            tokens = offset_raw
+        elif isinstance(offset_raw, str):
+            tokens = offset_raw.split(",")
+        else:
+            return []
+
+        offsets = []
+        for token in tokens:
+            value = str(token).strip()
+            if not value:
+                continue
+            try:
+                offsets.append(int(value))
+            except ValueError:
+                continue
+        return offsets
+
+    @staticmethod
+    def _parse_keywords(keyword_raw):
+        """
+        Parse OEIS keyword field into a list of strings.
+
+        Typical OEIS values look like ``"nonn,easy"`` and are returned as
+        ``["nonn", "easy"]``.
+        """
+        if isinstance(keyword_raw, list):
+            tokens = keyword_raw
+        elif isinstance(keyword_raw, str):
+            tokens = keyword_raw.split(",")
+        else:
+            return []
+
+        keywords = []
+        for token in tokens:
+            value = str(token).strip()
+            if value:
+                keywords.append(value)
+        return keywords
+
+__all__ = ["__version__",
+            "check_id",
+            "oeis_bfile",
+            "oeis_url",
+            "OEIS_URL",
+            "BFile",
+            "Sequence"]

oeis_tools-0.1.0/src/oeis_tools/utils.py

@@ -0,0 +1,77 @@
+"""
+Utility functions for working with OEIS identifiers and URLs.
+
+This module provides small, self-contained helpers related to the
+Online Encyclopedia of Integer Sequences (OEIS), including:
+
+- Validation of OEIS sequence identifiers (e.g. ``A000001``).
+- Construction of b-file filenames.
+- Generation of OEIS URLs in different formats (web, JSON, text, b-file).
+
+The functions in this module are pure utilities: they perform no network
+requests and have no side effects beyond basic validation.
+"""
+
+import re
+
+OEIS_URL = "https://oeis.org"
+
+def check_id(oeis_id):
+    """
+    Check if the OEIS ID is valid.
+    It must start with 'A' followed by exactly 6 digits.
+    
+    Args:
+        oeis_id (str): The ID to check.
+    
+    Returns:
+        bool: True if valid, False otherwise.
+    """
+    pattern = r'^A\d{6}$'
+    return bool(re.match(pattern, oeis_id))
+
+def oeis_bfile(oeis_id):
+    """
+    Generate the b-file filename for a given OEIS ID.
+    
+    The b-file is a text file containing the sequence data.
+    The filename format is 'b' followed by the 6-digit number and '.txt'.
+    
+    Args:
+        oeis_id (str): A valid OEIS ID, e.g., 'A000001'.
+    
+    Returns:[print(item[0]) for item in json_dict()]
+        str: The b-file filename, e.g., 'b000001.txt'.
+    
+    Raises:
+        ValueError: If the oeis_id is not in the correct format.
+    """
+    if not check_id(oeis_id):
+        raise ValueError(f"Invalid OEIS ID: {oeis_id}")
+
+    # Extract the 6 digits after 'A'
+    digits = oeis_id[1:]
+    return f"b{digits}.txt"
+
+def oeis_url(oeis_id, fmt=None):
+    """
+    Generate the OEIS webpage URL for a given OEIS ID.
+    
+    Args:
+        oeis_id (str): The OEIS ID, e.g., 'A000001'.
+        fmt (str, optional): The format of the response. 
+            - 'json': JSON search URL.
+            - 'text': Text search URL.
+            - 'bfile': b-file URL.
+            - None: Standard webpage URL.
+    
+    Returns:
+        str: The URL.
+    """
+    formats = {
+        "json": f"{OEIS_URL}/search?q=id:{oeis_id}&fmt=json",
+        "text": f"{OEIS_URL}/search?q=id:{oeis_id}&fmt=text",
+        "bfile": f"{OEIS_URL}/{oeis_id}/{oeis_bfile(oeis_id)}",
+        None: f"{OEIS_URL}/{oeis_id}",
+    }
+    return formats.get(fmt, formats[None])

oeis_tools-0.1.0/src/oeis_tools.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: oeis-tools
+Version: 0.1.0
+Summary: Tools and utilities for working with OEIS integer sequences
+Author-email: Enrique Pérez Herrero <energycode.org@gmail.com>
+License-Expression: MIT
+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
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Dynamic: license-file
+
+# oeis-tools
+
+[![Tests](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml/badge.svg)](https://github.com/oeistools/oeis-tools/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/oeis-tools.svg)](https://pypi.org/project/oeis-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`oeis-tools` is a Python package for working with the
+[Online Encyclopedia of Integer Sequences (OEIS)](https://oeis.org/).
+
+It provides:
+- OEIS ID validation
+- URL and b-file helpers
+- A `Sequence` class for OEIS JSON entries
+- A `BFile` class for b-file numeric data
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install oeis-tools
+```
+
+From source:
+
+```bash
+git clone https://github.com/oeistools/oeis-tools.git
+cd oeis-tools
+pip install -e .
+```
+
+Development dependencies (tests):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import oeis_tools
+
+# Utilities
+print(oeis_tools.check_id("A000001"))              # True
+print(oeis_tools.oeis_bfile("A000001"))            # b000001.txt
+print(oeis_tools.oeis_url("A000001", fmt="json"))  # https://oeis.org/search?q=id:A000001&fmt=json
+
+# Sequence API
+seq = oeis_tools.Sequence("A000045")
+print(seq.name)        # Fibonacci numbers
+print(seq.data)        # comma-separated terms
+print(seq.author)      # list[str]
+print(seq.json["id"])  # raw JSON field access
+
+# B-file API
+bfile = oeis_tools.BFile("A000045")
+print(bfile.get_filename())      # b000045.txt
+print(bfile.get_url())           # https://oeis.org/A000045/b000045.txt
+print(bfile.get_bfile_data()[:5])
+```
+
+## API Overview
+
+- `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)`
+  - Key attributes: `id`, `json`, `name`, `data`, `author`, `link`, `bfile`
+- `BFile(oeis_id: str)`
+  - Methods: `get_filename()`, `get_url()`, `get_bfile_data()`
+
+## Running Tests
+
+```bash
+pytest -q
+```
+
+## License
+
+MIT. See `LICENSE`.
+
+## Author
+
+Enrique Pérez Herrero - [energycode.org@gmail.com](mailto:energycode.org@gmail.com)

oeis_tools-0.1.0/src/oeis_tools.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/oeis_tools/__init__.py
+src/oeis_tools/__version__.py
+src/oeis_tools/bfile.py
+src/oeis_tools/sequence.py
+src/oeis_tools/utils.py
+src/oeis_tools.egg-info/PKG-INFO
+src/oeis_tools.egg-info/SOURCES.txt
+src/oeis_tools.egg-info/dependency_links.txt
+src/oeis_tools.egg-info/requires.txt
+src/oeis_tools.egg-info/top_level.txt
+tests/conftest.py
+tests/test_bfile.py
+tests/test_sequence.py
+tests/test_utils.py

oeis_tools-0.1.0/src/oeis_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oeis_tools-0.1.0/src/oeis_tools.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31
+
+[dev]
+pytest>=7.4

oeis_tools-0.1.0/src/oeis_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+oeis_tools

oeis_tools-0.1.0/tests/conftest.py

@@ -0,0 +1,10 @@
+"""Pytest configuration for local source imports."""
+
+from pathlib import Path
+import sys
+
+
+SRC_DIR = Path(__file__).resolve().parents[1] / "src"
+src_path = str(SRC_DIR)
+if src_path not in sys.path:
+    sys.path.insert(0, src_path)

oeis_tools-0.1.0/tests/test_bfile.py

@@ -0,0 +1,55 @@
+"""Tests for ``oeis_tools.bfile.BFile``."""
+
+import requests
+
+from oeis_tools.bfile import BFile
+
+
+class DummyResponse:
+    """Minimal response object used to mock ``requests.get``."""
+
+    def __init__(self, text):
+        """Store raw text returned by the fake request."""
+        self.text = text
+
+    def raise_for_status(self):
+        """Mimic a successful HTTP response."""
+        return None
+
+
+def test_bfile_parses_numeric_values_and_metadata(monkeypatch):
+    """Parse b-file values and expose expected filename and URL."""
+    def fake_get(url, timeout):
+        assert "A000045" in url
+        assert timeout == 10
+        return DummyResponse("# comment\n0 0\n1 1\n2 1\n3 2\n")
+
+    monkeypatch.setattr("oeis_tools.bfile.requests.get", fake_get)
+
+    bfile = BFile("A000045")
+
+    assert bfile.get_filename() == "b000045.txt"
+    assert bfile.get_url() == "https://oeis.org/A000045/b000045.txt"
+    assert bfile.get_bfile_data() == [0, 1, 1, 2]
+
+
+def test_bfile_returns_none_when_request_fails(monkeypatch):
+    """Return ``None`` when the HTTP request fails."""
+    def fake_get(url, timeout):
+        raise requests.RequestException("network error")
+
+    monkeypatch.setattr("oeis_tools.bfile.requests.get", fake_get)
+
+    bfile = BFile("A000045")
+    assert bfile.get_bfile_data() is None
+
+
+def test_bfile_returns_none_for_malformed_line(monkeypatch):
+    """Return ``None`` when a b-file line cannot be parsed."""
+    def fake_get(url, timeout):
+        return DummyResponse("0 0\nthis-is-not-valid\n")
+
+    monkeypatch.setattr("oeis_tools.bfile.requests.get", fake_get)
+
+    bfile = BFile("A000045")
+    assert bfile.get_bfile_data() is None

oeis_tools-0.1.0/tests/test_sequence.py

@@ -0,0 +1,235 @@
+"""Tests for ``oeis_tools.sequence.Sequence``."""
+
+from datetime import datetime
+
+import pytest
+import requests
+
+from oeis_tools.sequence import Sequence
+
+
+class DummyResponse:
+    """Minimal JSON response object for mocking API calls."""
+
+    def __init__(self, payload, error=None):
+        """Store mock payload and optional HTTP error."""
+        self._payload = payload
+        self._error = error
+
+    def raise_for_status(self):
+        """Raise the configured HTTP error when present."""
+        if self._error:
+            raise self._error
+        return None
+
+    def json(self):
+        """Return the stored JSON payload."""
+        return self._payload
+
+
+class DummyBFile:
+    """Simple placeholder used to avoid network calls in ``Sequence``."""
+
+    def __init__(self, oeis_id):
+        """Keep the sequence ID passed by ``Sequence``."""
+        self.oeis_id = oeis_id
+
+    def get_filename(self):
+        """Provide default b-file filename in tests."""
+        return "b000001.txt"
+
+    def get_url(self):
+        """Provide default b-file URL in tests."""
+        return "https://oeis.org/A000001/b000001.txt"
+
+    def get_bfile_data(self):
+        """Default to no parsed b-file data."""
+        return None
+
+
+def test_sequence_parses_json_fields_and_builds_links(monkeypatch):
+    """Parse key OEIS fields, datetimes, links, and b-file integration."""
+    payload = [
+        {
+            "id": "M1234 N5678",
+            "data": "1,1,2,3,5,8",
+            "name": "Fibonacci numbers",
+            "comment": ["First comment", "Second comment"],
+            "reference": ["Ref A", "Ref B"],
+            "formula": ["a(n)=a(n-1)+a(n-2)"],
+            "example": ["a(5)=5"],
+            "maple": ["seq(fibonacci(n),n=0..10);"],
+            "mathematica": ["Table[Fibonacci[n], {n,0,10}]"],
+            "program": ["Python: ..."],
+            "xref": ["Cf. A000204"],
+            "keyword": "nonn",
+            "offset": "0,2",
+            "author": "_Tom Verhoeff_, _N. J. A. Sloane_",
+            "references": ["Some extra reference"],
+            "revision": "42",
+            "time": "2024-01-02 03:04:05",
+            "created": "2000-01-01 00:00:00",
+            "link": [
+                '<a href="/A000045">Main entry</a>',
+                '<a href="https://example.com/ref">External ref</a>',
+                'See also <a href="/wiki">wiki</a>',
+            ],
+        }
+    ]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000045")
+
+    assert seq.id == "A000045"
+    assert seq.m_id == "M1234"
+    assert seq.n_id == "N5678"
+    assert seq.name == "Fibonacci numbers"
+    assert seq.comment == "First comment\nSecond comment"
+    assert seq.reference == "Ref A\nRef B"
+    assert seq.author == ["Tom Verhoeff", "N. J. A. Sloane"]
+    assert seq.keyword == ["nonn"]
+    assert seq.offset == [0, 2]
+    assert seq.time == datetime(2024, 1, 2, 3, 4, 5)
+    assert seq.created == datetime(2000, 1, 1, 0, 0, 0)
+    assert "[Main entry](https://oeis.org/A000045)" in seq.link
+    assert "[External ref](https://example.com/ref)" in seq.link
+    assert "[wiki](https://oeis.org/wiki)" in seq.link
+    assert isinstance(seq.bfile, DummyBFile)
+    assert seq.bfile.oeis_id == "A000045"
+
+
+def test_sequence_rejects_invalid_oeis_id():
+    """Raise ``ValueError`` for invalid OEIS identifiers."""
+    with pytest.raises(ValueError, match="Invalid OEIS ID"):
+        Sequence("invalid-id")
+
+
+def test_sequence_propagates_http_error(monkeypatch):
+    """Propagate HTTP errors from the JSON endpoint."""
+    def fake_get(url, timeout):
+        return DummyResponse(payload=None, error=requests.HTTPError("request failed"))
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", fake_get)
+
+    with pytest.raises(requests.HTTPError, match="request failed"):
+        Sequence("A000001")
+
+
+def test_sequence_author_ignores_trailing_year_tokens(monkeypatch):
+    """Drop year-only entries when parsing the OEIS author field."""
+    payload = [
+        {
+            "id": "M0001 N0001",
+            "author": "_N. J. A. Sloane_, 1964",
+            "link": [],
+        }
+    ]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000001")
+    assert seq.author == ["N. J. A. Sloane"]
+
+
+def test_sequence_author_ignores_trailing_full_date_tokens(monkeypatch):
+    """Drop full date entries when parsing the OEIS author field."""
+    payload = [
+        {
+            "id": "M0001 N0001",
+            "author": "_Pierre CAMI_, Apr 28 2012",
+            "link": [],
+        }
+    ]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000001")
+    assert seq.author == ["Pierre CAMI"]
+
+
+def test_sequence_offset_ignores_invalid_tokens(monkeypatch):
+    """Parse integer offsets and ignore malformed tokens."""
+    payload = [
+        {
+            "id": "M0001 N0001",
+            "offset": "1, bad, -3",
+            "link": [],
+        }
+    ]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000001")
+    assert seq.offset == [1, -3]
+
+
+def test_sequence_keyword_splits_and_ignores_empty_tokens(monkeypatch):
+    """Parse keywords into a list and drop empty entries."""
+    payload = [
+        {
+            "id": "M0001 N0001",
+            "keyword": "nonn, easy, ,look",
+            "link": [],
+        }
+    ]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000001")
+    assert seq.keyword == ["nonn", "easy", "look"]
+
+
+def test_sequence_get_bfile_info_with_data(monkeypatch):
+    """Return metadata and stats when b-file data is available."""
+    payload = [{"id": "M0001 N0001", "link": []}]
+
+    class BFileWithData(DummyBFile):
+        def get_filename(self):
+            return "b000045.txt"
+
+        def get_url(self):
+            return "https://oeis.org/A000045/b000045.txt"
+
+        def get_bfile_data(self):
+            return [0, 1, 1, 2, 3]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", BFileWithData)
+
+    seq = Sequence("A000001")
+    info = seq.get_bfile_info()
+
+    assert info["available"] is True
+    assert info["filename"] == "b000045.txt"
+    assert info["url"] == "https://oeis.org/A000045/b000045.txt"
+    assert info["length"] == 5
+    assert info["first"] == 0
+    assert info["last"] == 3
+    assert info["min"] == 0
+    assert info["max"] == 3
+
+
+def test_sequence_get_bfile_info_without_data(monkeypatch):
+    """Return unavailable metadata when b-file data is missing."""
+    payload = [{"id": "M0001 N0001", "link": []}]
+
+    monkeypatch.setattr("oeis_tools.sequence.requests.get", lambda url, timeout: DummyResponse(payload))
+    monkeypatch.setattr("oeis_tools.sequence.BFile", DummyBFile)
+
+    seq = Sequence("A000001")
+    info = seq.get_bfile_info()
+
+    assert info["available"] is False
+    assert info["filename"] == "b000001.txt"
+    assert info["url"] == "https://oeis.org/A000001/b000001.txt"
+    assert info["length"] == 0
+    assert info["first"] is None
+    assert info["last"] is None
+    assert info["min"] is None
+    assert info["max"] is None

oeis_tools-0.1.0/tests/test_utils.py

@@ -0,0 +1,42 @@
+"""Tests for utility helpers in ``oeis_tools.utils``."""
+
+import pytest
+
+from oeis_tools.utils import OEIS_URL, check_id, oeis_bfile, oeis_url
+
+
+def test_check_id_accepts_valid_oeis_id():
+    """Accept IDs that match the OEIS pattern."""
+    assert check_id("A000001") is True
+
+
+def test_check_id_rejects_invalid_oeis_ids():
+    """Reject IDs with wrong prefix or wrong length/characters."""
+    assert check_id("A12345") is False
+    assert check_id("B000001") is False
+    assert check_id("A0000012") is False
+    assert check_id("A12ABC") is False
+
+
+def test_oeis_bfile_builds_expected_filename():
+    """Build the expected OEIS b-file filename from a valid ID."""
+    assert oeis_bfile("A000045") == "b000045.txt"
+
+
+def test_oeis_bfile_raises_for_invalid_id():
+    """Raise ``ValueError`` when b-file is requested for an invalid ID."""
+    with pytest.raises(ValueError, match="Invalid OEIS ID"):
+        oeis_bfile("A123")
+
+
+def test_oeis_url_builds_supported_formats():
+    """Generate valid OEIS URLs for default and known formats."""
+    assert oeis_url("A000001") == f"{OEIS_URL}/A000001"
+    assert oeis_url("A000001", fmt="json") == f"{OEIS_URL}/search?q=id:A000001&fmt=json"
+    assert oeis_url("A000001", fmt="text") == f"{OEIS_URL}/search?q=id:A000001&fmt=text"
+    assert oeis_url("A000001", fmt="bfile") == f"{OEIS_URL}/A000001/b000001.txt"
+
+
+def test_oeis_url_falls_back_to_default_for_unknown_format():
+    """Use the default entry URL when an unknown format is provided."""
+    assert oeis_url("A000001", fmt="unknown") == f"{OEIS_URL}/A000001"