Metadata-Version: 2.4
Name: tomlplus
Version: 1.0.3
Summary: TOML+ — an extended configuration format with dictionaries, annotations, and variables
Author-email: Carson Kopec <kopeccarson@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/CarsonKopec/tomlplus
Project-URL: Repository, https://github.com/CarsonKopec/tomlplus
Keywords: toml,config,configuration,parser,annotations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"

# TOML+

A Python library for the **TOML+** configuration format — TOML extended with inline/block dictionaries, annotations, and variables.

```toml
[vars]
base_url = "https://api.example.com"

[server]
@tag: owner = "platform"

@type: int
@min: 1
@max: 65535
port = $ENV.PORT ?? 8080

cors = #{
  @required
  access-control-allow-origin = $base_url
}#
```

---

## Installation

```bash
pip install tomlplus
```

Or from source:

```bash
git clone https://github.com/CarsonKopec/tomlplus
cd tomlplus
pip install -e ".[dev]"
```

---

## Quick Start

```python
import tomlplus

# Parse from string
doc = tomlplus.loads("""
[database]
@required
@type: string
host = $ENV.DB_HOST ?? "localhost"

@type: int
@min: 1
@max: 65535
port = 5432
""")

# Dict-like access
print(doc["database"]["port"])   # 5432

# Dotted path access
print(doc.resolve("database.host"))  # "localhost" (or $DB_HOST if set)

# Parse and validate in one step
doc = tomlplus.loads_validated(source)

# Load from file
doc = tomlplus.load("config.tomlp")
doc = tomlplus.load_validated("config.tomlp")
```

---

## Format Features

### Sections & key/value pairs

Standard TOML syntax — all TOML primitives are supported.

```toml
[app]
name    = "MyService"
version = "1.0.0"
debug   = false
workers = 4
tags    = ["web", "api"]
```

### Block Dictionaries

```toml
[server]
headers = #{
  content-type = "application/json"
  cache-control = "no-cache"
}#
```

### Annotations

```toml
@required
@type: string
@minlen: 3
@maxlen: 64
@pattern: "^[a-z0-9_-]+$"
username = "admin"

@type: int
@min: 1
@max: 65535
port = 8080

@type: string
@enum: [debug, info, warn, error]
log_level = "info"

@deprecated("Use connection_string instead")
db_url = "postgres://localhost/mydb"

@tag: owner = "platform-team"
@tag: sensitivity = "secret"
api_key = $ENV.API_KEY
```

### Variables

```toml
[vars]
base_url = "https://api.example.com"
timeout  = 30

[service]
endpoint       = $base_url + "/v2/data"
read_timeout   = $timeout
connect_timeout = $timeout * 2

# Environment variable with fallback
log_level = $ENV.LOG_LEVEL ?? "info"

# Built-in constants
deployed_at = $NOW
hostname    = $HOSTNAME
platform    = $PLATFORM
```

**Built-in variables:** `$NOW`, `$TODAY`, `$TRUE`, `$FALSE`, `$NULL`, `$PID`, `$HOSTNAME`, `$PLATFORM`, `$CWD`

---

## Python API

### Parsing

```python
tomlplus.loads(source: str) -> TOMLPlusDocument
tomlplus.load(path)         -> TOMLPlusDocument
tomlplus.loads_validated(source: str) -> TOMLPlusDocument   # parse + validate
tomlplus.load_validated(path)         -> TOMLPlusDocument
```

### TOMLPlusDocument

```python
doc["server"]["port"]               # dict-style access
doc.get("missing", default)         # safe access
doc.resolve("server.port")          # dotted-path access
doc.resolve("missing.key", default) # with default

doc.annotations("server.port")      # → list[Annotation]
doc.has_annotation("port", "required")
doc.tags("database")                # → {"owner": "billing"}
doc.required_keys()                 # → ["api_key", "db.host", ...]
doc.deprecated_keys()               # → [("old_url", "use new_url")]
doc.keys_with_tag("owner")          # → [("app", "platform"), ...]

doc.config   # raw dict
doc.meta     # annotation metadata dict
doc.vars     # user-defined variables from [vars]
```

### Validation

```python
# Raises ValidationError on first failure
tomlplus.validate(doc)

# Collects all failures
errors = tomlplus.validate_all(doc)
for err in errors:
    print(err)
```

### Serialization

```python
tomlplus.dumps(doc)    # TOMLPlusDocument → TOML+ string
tomlplus.dumps(d)      # plain dict → TOML+ string
```

### Errors

```python
from tomlplus import TOMLPlusError, ParseError, ValidationError, VariableError

try:
    doc = tomlplus.load_validated("config.tomlp")
except ParseError as e:
    print(f"Syntax error at line {e.line}: {e}")
except VariableError as e:
    print(f"Undefined variable: {e.variable}")
except ValidationError as e:
    print(f"Invalid value for {e.key}: {e}")
```

---

## CLI

```bash
# Parse and output JSON
tomlplus parse config.tomlp
tomlplus parse config.tomlp -o out.json

# Validate all annotation constraints
tomlplus validate config.tomlp

# Show annotation metadata
tomlplus meta config.tomlp

# Show resolved variables
tomlplus vars config.tomlp
tomlplus vars config.tomlp --all   # also show built-ins

# Round-trip format
tomlplus fmt config.tomlp
tomlplus fmt config.tomlp -o formatted.tomlp
```

---

## Running Tests

```bash
pip install -e ".[dev]"
pytest
pytest --cov=tomlplus --cov-report=term-missing
```

---

## File Extension

TOML+ files use the `.tomlp` extension with MIME type `application/x-tomlplus`.

---

## License

MIT
