# Chalk Python SDK Reference: Utils
source: https://docs.chalk.ai/api-docs#section-utils

## `Duration`
source: https://docs.chalk.ai/api-docs#Duration

Type alias: `str | timedelta | Literal['infinity' | 'all']`

Duration is used to describe time periods in natural language. To specify using natural language, write the count of the unit you would like, followed by the representation of the unit.

Chalk supports the following units:

| Signifier | Meaning |
| --- | --- |
| w | Weeks |
| d | Days |
| h | Hours |
| m | Minutes |
| s | Seconds |
| ms | Milliseconds |

As well as the special keywords `"infinity"` and `"all"`.

Examples:

| Signifier | Meaning |
| --- | --- |
| "10h" | 10 hours |
| "1w 2m" | 1 week and 2 minutes |
| "1h 10m 2s" | 1 hour, 10 minutes, and 2 seconds |
| "infinity" and "all" | Unbounded time duration |

## `CronTab`
source: https://docs.chalk.ai/api-docs#CronTab

Type alias: `str`

A schedule defined using the Unix-cron string format (`* * * * *`). Values are given in the order below:

| Field | Values |
| --- | --- |
| Minute | 0-59 |
| Hour | 0-23 |
| Day of Month | 1-31 |
| Month | 1-12 |
| Day of Week | 0-6 |

## `Environments`
source: https://docs.chalk.ai/api-docs#Environments

Type alias: `str | Sequence[str]`

Environments are used to trigger behavior in different deployments such as staging, production, and local development. For example, you may wish to interact with a vendor via an API call in the production environment, and opt to return a constant value in a staging environment.

[`Environments`](https://docs.chalk.ai/api-docs#Environments) can take one of three types:

- [`None`](https://docs.python.org/3/library/constants.html#None) (default) - candidate to run in every environment
- [`str`](https://docs.python.org/3/library/stdtypes.html#str) - run only in this environment
- `list[str]` - run in any of the specified environment and no others

See more at [Environments](https://docs.chalk.ai/docs/resolver-environments)

## `Tags`
source: https://docs.chalk.ai/api-docs#Tags

Type alias: `str | Sequence[str]`

Tags allow you to scope requests within an environment. Both tags and environment need to match for a resolver to be a candidate to execute.

Like Environments, tags control when resolvers run based on the Online Context or Training Context matching the tags provided to the resolver decorator. Resolvers optionally take a keyword argument named tags that can take one of three types:

- [`None`](https://docs.python.org/3/library/constants.html#None) (default) - The resolver will be a candidate to run for every set of tags.
- [`str`](https://docs.python.org/3/library/stdtypes.html#str) - The resolver will run only if this tag is provided.
- `list[str]` - The resolver will run in all of the specified tags match.

See more at [Routing tags](https://docs.chalk.ai/docs/resolver-tags)

## `owner(f)`
source: https://docs.chalk.ai/api-docs#owner

Get the owner for a feature, feature class, or resolver.

**Parameters**

- `f`: `Any`
  A feature (`User.email`), feature class (`User`), or resolver (`get_user`)

**Returns**

`str | None`

The owner for a feature or feature class, if it exists. Note that the owner of a feature could be inherited from the feature class.

**Raises**

- `TypeError`: If the supplied variable is not a feature, feature class, or resolver.

**Examples**

```python
@features(owner="ship")
class RocketShip:
    id: int
    software_version: str
owner(RocketShip.software_version)
```

```python
'ship'
```

## `tags(f)`
source: https://docs.chalk.ai/api-docs#tags

Get the tags for a feature, feature class, or resolver.

**Parameters**

- `f`: `Any`
  A feature (`User.email`), feature class (`User`), or resolver (`get_user`)

**Returns**

`Sequence[str] | None`

The tags for a feature, feature class, or resolver, if it exists. Note that the tags of a feature could be inherited from the feature class.

**Raises**

- `TypeError`: If the supplied variable is not a feature, feature class, or resolver.

**Examples**

Feature tags

```python
@features(tags="group:risk")
class User:
    id: str
    # :tags: pii
    email: str
tags(User.id)
```

```python
['group:risk']
```

Feature class tags

```python
tags(User)
```

```python
['group:risk']
```

Feature + feature class tags

```python
tags(User.email)
```

```python
['pii', 'group:risk']
```

## `description(f)`
source: https://docs.chalk.ai/api-docs#description

Get the description of a feature, feature class, or resolver.

**Parameters**

- `f`: `Any`
  A feature (`User.email`), feature class (`User`), or resolver (`get_user`)

**Returns**

`str | None`

The description for a feature, feature class, or resolver, if it exists.

**Raises**

- `TypeError`: If the supplied variable is not a feature, feature class, or resolver.

**Examples**

```python
@features
class RocketShip:
    # Comments above a feature become
    # descriptions for the feature!
    software_version: str
description(RocketShip.software_version)
```

```python
'Comments above a feature become descriptions for the feature!'
```

## `is_primary(f)`
source: https://docs.chalk.ai/api-docs#is_primary

Determine whether a feature is a primary key.

**Parameters**

- `f`: `Any`
  A feature (i.e. `User.email`)

**Returns**

`bool`

[`True`](https://docs.python.org/3/library/constants.html#True) if `f` is primary and [`False`](https://docs.python.org/3/library/constants.html#False) otherwise.

**Raises**

- `TypeError`: If `f` is not a feature.

**Examples**

```python
from chalk.features import features
from chalk import Primary
@features
class User:
    uid: Primary[int]
    email: str
assert is_primary(User.uid)
assert not is_primary(User.email)
```

## `is_feature_time(f)`
source: https://docs.chalk.ai/api-docs#is_feature_time

Determine whether a feature is a feature time. See [Time Overview](https://docs.chalk.ai/docs/time) for more details on `FeatureTime`.

**Parameters**

- `f`: `Any`
  A feature (i.e. `User.ts`)

**Returns**

`bool`

[`True`](https://docs.python.org/3/library/constants.html#True) if the feature is a `FeatureTime` and [`False`](https://docs.python.org/3/library/constants.html#False) otherwise.

**Examples**

```python
from chalk.features import features, FeatureTime
@features
class User:
    id: str
    updated_at: FeatureTime
assert is_feature_time(User.updated_at) is True
assert is_feature_time(User.id) is False
```

## `AnyDataclass`
source: https://docs.chalk.ai/api-docs#AnyDataclass

Type alias: `Any`

Any class decorated by [`@dataclass`](https://docs.python.org/3/library/dataclasses.html).

There isn't a base class for [`dataclass`](https://docs.python.org/3/library/dataclasses.html), so we use this [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias ) to refer to indicate any class decorated with [`@dataclass`](https://docs.python.org/3/library/dataclasses.html).

## `ChalkBaseException`
source: https://docs.chalk.ai/api-docs#ChalkBaseException

Exception (bases: `Exception`)

The base type for Chalk exceptions.

This exception makes error handling easier, as you can look only for this exception class.

**Attributes**

- `message`: `str`
  A message describing the specific type of exception raised.
- `full_message`: `str`
  A message that describes the specific type of exception raised and contains the readable representation of each error in the errors attribute.

  Also includes the trace ID if one is available.
