rhylthyme-importers 0.3.0
Import plugins for converting external data sources to Rhylthyme programs
License: Apache-2.0
Requires Python: >=3.12
Keywords: rhylthyme, scheduling, recipes, protocols, import

# Rhylthyme Importers

Import plugins for converting external data sources into Rhylthyme programs.

## Installation

```bash
pip install -e ./rhylthyme-importers
```

## Available Importers

### TheMealDB Importer

Import recipes from [TheMealDB](https://www.themealdb.com/) free recipe API.

```bash
# Search for recipes
rhylthyme-import search "chicken curry" -i themealdb

# Import by URL or meal ID
rhylthyme-import import "https://www.themealdb.com/meal/52772" -o curry.json --pretty

# Import a random meal
rhylthyme-import mealdb random -o random_meal.json --pretty

# List available categories
rhylthyme-import mealdb categories
```

### Protocols.io Importer

Import laboratory protocols from [protocols.io](https://www.protocols.io/).

**Requires API token:** Set the `PROTOCOLS_IO_TOKEN` environment variable with your
protocols.io API token (get one from https://www.protocols.io/developers).

```bash
export PROTOCOLS_IO_TOKEN="your_token_here"

# Search for protocols
rhylthyme-import search "western blot" -i protocolsio

# Import a protocol
rhylthyme-import import "https://www.protocols.io/view/western-blot-..." -o protocol.json --pretty
```

## CLI Commands

```bash
# List all available importers
rhylthyme-import list

# Import from any supported URL (auto-detects importer)
rhylthyme-import import <url> [-o output.json] [--pretty]

# Search using a specific importer
rhylthyme-import search <query> -i <importer>
```

## Python API

```python
from rhylthyme_importers import TheMealDBImporter, ProtocolsIOImporter, ImporterRegistry

# TheMealDB
mealdb = TheMealDBImporter()
results = mealdb.search("pasta")
result = mealdb.import_from_url("52771")

if result.success:
    program = result.program
    print(f"Imported: {program['name']}")

# Protocols.io
protocolsio = ProtocolsIOImporter(access_token="your_token")
result = protocolsio.import_from_url("https://www.protocols.io/view/...")

# Auto-detect importer from URL
importer = ImporterRegistry.find_for_url("https://www.themealdb.com/meal/52771")
if importer:
    result = importer.import_from_url("https://www.themealdb.com/meal/52771")
```

## Creating Custom Importers

Extend the `BaseImporter` class to create new importers:

```python
from rhylthyme_importers import BaseImporter, ImportResult, ImporterRegistry

class MyCustomImporter(BaseImporter):
    name = "myimporter"
    description = "Import from my custom source"
    supported_domains = ["example.com"]

    def can_import(self, url_or_query: str) -> bool:
        return "example.com" in url_or_query

    def search(self, query: str) -> list:
        # Return list of {name, url, description}
        return []

    def import_from_url(self, url: str) -> ImportResult:
        # Fetch data and convert to Rhylthyme program
        program = self.create_base_program(
            name="My Program",
            description="Description",
            environment_type="kitchen",
            source_url=url,
            source_type="myimporter"
        )
        # Add tracks, steps, etc.
        return ImportResult(success=True, program=program)

# Register the importer
ImporterRegistry.register(MyCustomImporter())
```

## Publishing to PyPI

To publish this package to PyPI:

```bash
# Install build tools
pip install build twine

# Build the package
cd rhylthyme-importers
python -m build

# Upload to TestPyPI first (optional)
python -m twine upload --repository testpypi dist/*

# Upload to PyPI
python -m twine upload dist/*
```

You'll need PyPI credentials configured in `~/.pypirc` or use environment variables:
- `TWINE_USERNAME` / `TWINE_PASSWORD` or
- `TWINE_API_TOKEN` (recommended)

## License

Apache License 2.0