Metadata-Version: 2.3
Name: rdfcodegen
Version: 0.1.0
Summary: Add your description here
Author: carlosmpv
Author-email: carlosmpv <carlosmpvaldes@gmail.com>
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# rdfcodegen

Generate typed code interfaces from RDF/Turtle ontologies (e.g., schema.org).

**Currently supports TypeScript output. Additional language generators planned.**

## In this README :point_down:

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Command line](#command-line)
  - [Python API](#python-api)
  - [Filtering specific classes](#filtering-specific-classes)
- [How it works](#how-it-works)
- [Roadmap](#roadmap)
- [Projects using this template](#projects-using-this-template)
- [FAQ](#faq)
- [Contributing](#contributing)

## Features

**rdfcodegen** parses RDF/Turtle ontology files (like [schema.org](https://schema.org/)) and generates language-specific code with full type definitions, documentation, and inheritance.

:rocket: **What it produces:**
- Type-safe interfaces/classes extracted from RDFS/OWL class hierarchies.
- JSDoc/Docstring comments pulled from `rdfs:comment` annotations.
- Automatic dependency resolution — request one class and get all its parent types and field types transitively.
- Primitive type mapping (e.g., `schema:Text` → `string`, `schema:Number` → `number`).

:computer: **Supported output languages:**
- [x] **TypeScript** — `interface` definitions with optional properties (`?`) and array types.
- [ ] Go (planned)
- [ ] Python (planned)

## Installation

```bash
pip install rdfcodegen
```

*Requires Python 3.9+ and [rdflib](https://github.com/RDFLib/rdflib).*

## Usage

### Command line

Generate TypeScript interfaces for all schema.org types:

```bash
rdfcodegen --ttl https://schema.org/version/latest/schemaorg-current-https.ttl \
           --namespace https://schema.org/ \
           --out schema.ts
```

Generate only specific classes (and everything they depend on):

```bash
rdfcodegen --class schema:Person --class schema:Organization --out schema.ts
```

Write to stdout (`-`):

```bash
rdfcodegen > schema.ts
```

**CLI options:**

| Option | Default | Description |
|---|---|---|
| `--ttl` | `schema.org/version/latest/schemaorg-current-https.ttl` | URL or path to Turtle file |
| `--namespace` | `https://schema.org/` | Ontology namespace URI |
| `--out` | `-` | Output file (`-` for stdout) |
| `--class` | (all classes) | Generate specific classes (repeatable) |

### Python API

```python
from rdfcodegen import TypescriptGenerator

gen = TypescriptGenerator()

# Generate all types
ts_code = gen.generate(
    ttl_url="https://schema.org/version/latest/schemaorg-current-https.ttl",
    namespace_url="https://schema.org/",
)

# Generate a subset
ts_code = gen.generate(
    chosen=["schema:Person", "schema:Event"],
    ttl_url="https://schema.org/version/latest/schemaorg-current-https.ttl",
    namespace_url="https://schema.org/",
)

with open("schema.ts", "w") as f:
    f.write(ts_code)
```

### Filtering specific classes

When you specify classes with `--class` (or the `chosen` parameter), the generator:

1. Includes the requested classes.
2. Recursively includes all **parent types** up the `rdfs:subClassOf` hierarchy.
3. Recursively includes all **field types** referenced via `schema:rangeIncludes`.
4. Skips primitive types (e.g., `schema:Text`, `schema:Number`) — these map directly to language primitives.

This ensures the generated output is always self-contained and compilable.

## How it works

1. **Parse** — The Turtle file is loaded into an RDF graph using `rdflib`.
2. **Discover classes** — All subjects typed as `rdfs:Class` within the target namespace are collected.
3. **Traverse hierarchy** — `rdfs:subClassOf` relationships are followed to build the class hierarchy.
4. **Collect properties** — `schema:domainIncludes` and `schema:rangeIncludes` are used to determine which fields belong to which classes and what types they return.
5. **Extract documentation** — `rdfs:comment` values become JSDoc/docstring comments.
6. **Resolve dependencies** — If filtering is requested, a dependency graph walk collects all transitive type references.
7. **Generate output** — A language-specific generator (e.g., `TypescriptGenerator`) emits the final code.

### TypeScript output example

From `schema:Person`, the generator produces:

```typescript
// THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT DIRECTLY.

/**
 * A person (alive, dead, undead, or fictional).
 */
export interface SchemaPerson extends SchemaThing {
  /**
   * An additional name for a Person, can be used for a middle name.
   */
  additionalName?: string[];
  /**
   * Physical address of the item.
   */
  address?: (SchemaPostalAddress | string)[];
  /**
   * Date of birth.
   */
  birthDate?: string[];
  // ... more fields
}
```

## Roadmap

- [ ] Typescript types generator
    - [ ] Helper function to generate JSON-LD from those structs
- [ ] Go struct generator with JSON tags
- [ ] Python dataclass/pydantic generator
- [ ] Choose other languages

## Contributing

If you find a bug :bug:, please open a [bug report](https://github.com/allenai/python-package-template/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
If you have an idea for an improvement or new feature :rocket:, please open a [feature request](https://github.com/allenai/python-package-template/issues/new?assignees=&labels=Feature+request&template=feature_request.md&title=).