Roskarl

https://pypi.org/project/roskarl/
Admin
Roskarl is a Python module providing helper functions for parsing, validating, and retrieving typed...
Tokens:1,965
Snippets:30
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install roskarl using uv

Source: https://pypi.org/project/roskarl

Use the uv package manager to install the roskarl module.

```bash
uv pip install roskarl
```

--------------------------------

### Parsing Basic Types

Source: https://pypi.org/project/roskarl

Examples of parsing common types like strings, booleans, integers, and floats from environment variables.

```python
value = env_var(name="STR_VAR", default="fallback")
```

```python
value = env_var_bool(name="BOOL_VAR")
```

```python
value = env_var_tz(name="TZ_VAR")
```

```python
value = env_var_list(name="LIST_VAR", separator="|")
```

```python
value = env_var_int(name="INT_VAR")
```

```python
value = env_var_float(name="FLOAT_VAR")
```

--------------------------------

### Parsing Paths and Enums

Source: https://pypi.org/project/roskarl

Helpers for filesystem paths and custom Enum classes.

```python
value = env_var_path(name="CONFIG_PATH", must_exist=True)
```

```python
from enum import Enum
class Mode(Enum):
    LIVE = "live"
    DRY_RUN = "dry-run"

value = env_var_enum(name="MODE", enum_class=Mode, required=True)
```

--------------------------------

### DSN Parsing and Encoding

Source: https://pypi.org/project/roskarl

Helpers for parsing Data Source Names and encoding passwords for DSN strings.

```python
from urllib.parse import quote
password = 'My$ecret!Pass@2024'
encoded = quote(password, safe='')
print(encoded)  # My%24ecret%21Pass%402024 <--- use this
```

```python
value = env_var_dsn(name="DSN_VAR")
```

```text
postgresql://username:password@hostname:5432/database_name
```

--------------------------------

### Run test suite with pytest

Source: https://pypi.org/project/roskarl

Execute the full test suite located in the tests directory.

```bash
pytest tests/
```

--------------------------------

### Parsing Datetime Strings

Source: https://pypi.org/project/roskarl

Helpers for parsing ISO8601 and RFC3339 formatted datetime strings.

```python
value = env_var_iso8601_datetime(name="DATETIME_VAR")
```

```python
value = env_var_rfc3339_datetime(name="DATETIME_VAR")
```

--------------------------------

### Importing Roskarl Helpers

Source: https://pypi.org/project/roskarl

Import the necessary environment variable parsing functions from the roskarl package.

```python
from roskarl import (
    env_var,
    env_var_bool,
    env_var_cron,
    env_var_custom,
    env_var_duration,
    env_var_enum,
    env_var_interval_expression,
    env_var_interval_expression_extended,
    env_var_float,
    env_var_int,
    env_var_iso8601_datetime,
    env_var_list,
    env_var_log_level,
    env_var_path,
    env_var_rfc3339_datetime,
    env_var_secret,
    env_var_tz,
    env_var_url,
    env_var_dsn,
    DSN,
    Secret,
)
```

--------------------------------

### env_var(name, default=None, required=False)

Source: https://pypi.org/project/roskarl

Retrieves an environment variable as a string. Returns None if not set, or a provided default value.

```APIDOC
## env_var(name, default=None, required=False)

### Description
Retrieves an environment variable as a string. If the variable is not set, it returns the default value or None. If required=True is passed, it raises an error if the variable is missing.

### Parameters
- **name** (str) - Required - The name of the environment variable.
- **default** (str) - Optional - Fallback value if the variable is not set.
- **required** (bool) - Optional - If True, raises an error if the variable is missing.

### Example
```python
value = env_var(name="STR_VAR", default="fallback")
```
```

--------------------------------

### Parsing Durations and Log Levels

Source: https://pypi.org/project/roskarl

Helpers for timedelta durations and standard Python logging levels.

```python
value = env_var_duration(name="REQUEST_TIMEOUT", default=timedelta(seconds=30))
# accepts: "30s", "5m", "1h30m", "500ms", "7d", "1h 30m"
```

```python
import logging
level = env_var_log_level(name="LOG_LEVEL", default=logging.INFO)
logging.basicConfig(level=level)
```

--------------------------------

### env_var_dsn(name, default=None, required=False)

Source: https://pypi.org/project/roskarl

Parses an environment variable as a DSN object.

```APIDOC
## env_var_dsn(name, default=None, required=False)

### Description
Parses a DSN string into a DSN object containing scheme, host, port, username, password, and database attributes.

### Example
```python
value = env_var_dsn(name="DSN_VAR")
```
```

--------------------------------

### Parsing Cron and Interval Expressions

Source: https://pypi.org/project/roskarl

Helpers for validating cron and interval-based time expressions.

```python
value = env_var_cron(name="CRON_VAR")
```

```python
value = env_var_interval_expression(name="INTERVAL_VAR")
```

```python
value = env_var_interval_expression_extended(name="INTERVAL_EXTENDED_VAR")
```

--------------------------------

### Custom Parsers

Source: https://pypi.org/project/roskarl

Use a custom callable to parse environment variables into specific types.

```python
from uuid import UUID
value = env_var_custom(name="UUID_VAR", parser=UUID, required=True)  # type: UUID
```

--------------------------------

### env_var_int(name, default=None, required=False)

Source: https://pypi.org/project/roskarl

Retrieves an environment variable as an integer.

```APIDOC
## env_var_int(name, default=None, required=False)

### Description
Parses an environment variable as an integer if the value is numeric.

### Example
```python
value = env_var_int(name="INT_VAR")
```
```

--------------------------------

### Parsing URLs and Secrets

Source: https://pypi.org/project/roskarl

Helpers for handling URLs and sensitive data that should not be logged.

```python
value = env_var_url(name="API_URL")
```

```python
key = env_var_secret(name="API_KEY", required=True)
print(key)            # ***
stripe.api_key = key.reveal()
```

--------------------------------

### env_var_bool(name, default=None, required=False)

Source: https://pypi.org/project/roskarl

Retrieves an environment variable as a boolean. Accepts 'true' or 'false' (case-insensitive).

```APIDOC
## env_var_bool(name, default=None, required=False)

### Description
Parses an environment variable as a boolean. Accepts 'true' or 'false' values regardless of case.

### Example
```python
value = env_var_bool(name="BOOL_VAR")
```
```

--------------------------------

### env_var_secret(name, required=False)

Source: https://pypi.org/project/roskarl

Retrieves an environment variable as a Secret object, preventing accidental logging.

```APIDOC
## env_var_secret(name, required=False)

### Description
Returns a Secret object that masks the value in logs. Use .reveal() to access the raw string.

### Example
```python
key = env_var_secret(name="API_KEY", required=True)
stripe.api_key = key.reveal()
```
```
Tokens:
Raw