### Inline credits example with Rich

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Demonstrates how to use Stat, money, and balance_style for inline Raycast output. It displays remaining balance and monthly spending with appropriate styling.

```python
from rich_raycast import Stat, balance_style, money, print_error, print_inline


def main() -> None:
    remaining = 12.34
    month_spend = 5.67

    print_inline(
        Stat("Remaining", money(remaining), style=balance_style(remaining)),
        Stat("This Month", money(month_spend), style="red"),
        refreshed_at=True,
    )
```

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

### Python script frontmatter with rich-raycast

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

This is an example of how the script's frontmatter is updated to include rich-raycast as a dependency. Ensure your Python version is compatible.

```python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "rich-raycast @ git+https://github.com/caentzminger/rich-raycast.git",
# ]
# ///
```

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

### period_bounds()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Calculates the start and end epoch seconds for a given time period unit.

```APIDOC
## period_bounds()

### Description
Calculates the start and end epoch seconds for a standardized time period (like a day, hour, week, or month) that contains the given timestamp. This is useful for grouping data by time blocks.

### Parameters
- `timestamp` (datetime | int | float | str | None): The timestamp to anchor the period to. Defaults to the current time if `None`.
- `unit` (str): The unit of the time period. Options include 'day', 'hour', 'week', 'month'. Defaults to 'day'.
- `block_size` (int): The number of units to include in the period. Defaults to 1.

### Returns
- `tuple[int, int]`: A tuple containing the start and end epoch seconds of the calculated period.
```

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

### console

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

A default Console instance pre-configured for Raycast environments.

```APIDOC
## console

### Description
A globally available `Console` object that is pre-configured with settings suitable for Raycast Script Commands.

### Type
`rich.console.Console`
```

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

### Run Tests with uv

Source: https://github.com/caentzminger/rich-raycast/blob/main/AGENTS.md

Execute all project tests using the uv run command.

```bash
uv run pytest
```

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

### Format Code with uv and Ruff

Source: https://github.com/caentzminger/rich-raycast/blob/main/AGENTS.md

Automatically format code according to style guidelines using Ruff via uv run.

```bash
uv run ruff format .
```

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

### Lint Code with uv and Ruff

Source: https://github.com/caentzminger/rich-raycast/blob/main/AGENTS.md

Check code for style and potential errors using Ruff via uv run.

```bash
uv run ruff check .
```

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

### Type Check with uv and ty

Source: https://github.com/caentzminger/rich-raycast/blob/main/AGENTS.md

Perform static type checking on the project using the ty tool via uv run.

```bash
uv run ty
```

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

### raycast_console()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Returns a Raycast-configured Console object with specific settings for terminal output.

```APIDOC
## raycast_console()

### Description
Returns a `Console` object pre-configured for Raycast environments, ensuring terminal compatibility and color output.

### Returns
- `Console`: A `rich.console.Console` instance with `force_terminal=True`, `color_system="truecolor"`, and `highlight=False`.
```

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

### now_label()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Formats the current local time into a human-readable label.

```APIDOC
## now_label()

### Description
Formats a given timestamp into a localized string, typically in a 'Month Day, Hour:Minute AM/PM' format. It accepts various input types for the timestamp.

### Parameters
- `timestamp`: Accepts `True`, a `datetime` object, an epoch `int`/`float`, an ISO string, a tooltime label, or a pre-formatted string. If `True` or omitted, it uses the current time.

### Returns
- `str`: A formatted string representing the local time.
```

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

### inline() / print_inline()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Constructs or prints a one-line Rich Text payload suitable for Raycast inline output.

```APIDOC
## inline() / print_inline()

### Description
These functions are used to create and display a single line of formatted text, often used for status updates in Raycast. They can optionally include a timestamp indicating when the information was last refreshed.

### Parameters
- `*stats`: Variable number of `Stat` objects to include in the output.
- `refreshed_at`: Can be `True`, a `datetime` object, an epoch `int`/`float`, an ISO string, a tooltime label, or a pre-formatted string. If `True`, it uses the current time.

### Returns
- `inline()`: Returns a Rich `Text` object representing the formatted line.
- `print_inline()`: Prints the formatted line to the console.
```

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

### Add rich-raycast to uv script command

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Use this command to add the library as a script dependency for your Python Raycast script. It updates the script's frontmatter to include the dependency.

```bash
uv add --script <script-name>.py https://github.com/caentzminger/rich-raycast.git
```

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

### money()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Formats a numeric value as a currency string.

```APIDOC
## money()

### Description
Formats a given numeric value into a currency string, typically prefixed with a dollar sign. This function does not add any Rich markup.

### Parameters
- `value` (int | float | Decimal): The numeric value to format.

### Returns
- `str`: The formatted currency string (e.g., "$12.34").
```

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

### balance_style() / cost_style()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Returns a Rich style string ('green' or 'red') based on the sign of a numeric value.

```APIDOC
## balance_style() / cost_style()

### Description
These functions return a Rich style string that indicates whether a numeric value represents a positive balance (green) or a cost/negative balance (red).

### Parameters
- `value` (int | float | Decimal): The numeric value to evaluate.

### Returns
- `str`: Returns 'green' if the value is non-negative, and 'red' if the value is negative.
```

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

### die()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Prints an error message and exits the script with a non-zero status code.

```APIDOC
## die()

### Description
This function is used for critical errors, such as missing environment variables or malformed API responses. It prints an error message using `print_error` and then terminates the script execution with a non-zero exit code (1), signaling failure.

### Parameters
- `message` (str): The error message to display before exiting.
```

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

### duration_label()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Formats a duration in seconds into a human-readable string.

```APIDOC
## duration_label()

### Description
Formats a given number of seconds into a human-readable duration string using different format options.

### Parameters
- `seconds` (int | float): The total duration in seconds.
- `form` (str): The desired output format. Options include:
    - `"compact"`: e.g., "15d"
    - `"phrase"`: e.g., "15 days"
    - `"clock"`: e.g., "3:0:10:10"
    - `"clock_phrase"`: e.g., "3 days, 0:10:10"
    Defaults to 'compact'.

### Returns
- `str`: The formatted duration string.
```

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

### print_status() / print_error()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Prints conventional short status or error messages to the console.

```APIDOC
## print_status() / print_error()

### Description
These functions provide a standardized way to print short status messages or error messages to the console, suitable for use in script commands.

### Parameters
- `message` (str): The message content to print.
- `...`: Additional arguments may be passed to the underlying Rich console printing methods.
```

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

### date_label()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Formats a timestamp into a standardized date string.

```APIDOC
## date_label()

### Description
Formats a timestamp into a standardized date string, supporting ISO format or simpler date representations.

### Parameters
- `timestamp` (datetime | int | float | str | None): The timestamp to format. Defaults to the current time if `None`.
- `form` (str): The desired output format. Options include: 'iso' (e.g., "2020-09-13T12:26:40Z"), 'iso_space' (e.g., "2020-09-13 12:26:40Z"), 'date' (e.g., "2020-09-13"), or 'compact' (e.g., "20200913"). Defaults to 'iso'.

### Returns
- `str`: The formatted date string.
```

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

### Stat

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Represents a data point for inline display, consisting of a label, a value, and an optional style.

```APIDOC
## Stat

### Description
A data structure used to represent a labeled piece of information for compact, inline display in Raycast. It holds a label, its corresponding value, and a Rich style to apply to the value.

### Usage
`Stat(label: str, value: str, style: str | Style | None = None)`

### Parameters
- **label** (str) - Required - The descriptive label for the data.
- **value** (str) - Required - The value to display.
- **style** (str | Style | None) - Optional - A Rich style string or object to format the value.
```

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

### stale_style()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Determines a Rich color style based on the age of data.

```APIDOC
## stale_style()

### Description
Returns a Rich color style ('green', 'cyan', 'yellow', or 'red') that visually represents the freshness of data based on how many seconds have passed since a reference point.

### Parameters
- `seconds_ago` (int | float): The number of seconds that have passed.
- `...`: Additional arguments may be accepted by the underlying implementation.

### Returns
- `str`: A Rich style string indicating data freshness: 'green' for <1m, 'cyan' for <1h, 'yellow' for <1d, and 'red' for older data.
```

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

### time_ago()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Calculates and formats the time elapsed since a given timestamp.

```APIDOC
## time_ago()

### Description
Calculates the time elapsed since a specified timestamp and returns it as a human-readable string (e.g., "just now", "5m ago", "2d ago"). For times older than a week, it defaults to a calendar date.

### Parameters
- `timestamp`: The reference timestamp. Accepts epoch seconds (int/float), ISO format string, or a `datetime` object.
- `now` (datetime | int | float | str | None): The current time to compare against. Defaults to the current time if `None`.
- `form` (str): The format for the output string. Options include 'compact' (default) or 'phrase' (for multi-unit phrases like '3 hours').

### Returns
- `str`: A string representing the time elapsed since the timestamp.
```

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

### compact_number()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Abbreviates large numbers into a more compact, readable format.

```APIDOC
## compact_number()

### Description
Abbreviates large numeric values using suffixes like 'k' for thousands, 'M' for millions, and 'T' for trillions. Useful for displaying large counts concisely.

### Parameters
- `value` (int | float | None): The number to abbreviate. If `None`, returns '-'.
- `places` (int): The number of decimal places to retain. Defaults to 1.

### Returns
- `str`: The abbreviated number string (e.g., "1.5k", "10M") or "-" if input is `None`.
```

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

### print_request_error()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Handles and prints errors related to HTTP requests.

```APIDOC
## print_request_error()

### Description
A utility function designed to handle and display errors that commonly occur during HTTP requests, such as `httpx.RequestError`, `httpx.HTTPStatusError`, or `ValueError`. It attempts to extract relevant information from the exception to provide a user-friendly error message. This function does not require `httpx` to be installed as a direct dependency.

### Parameters
- `exc` (Exception): The exception object caught during an HTTP request.

### Behavior
- Gracefully handles exceptions by checking for a `response` attribute on the exception.
- Prints an informative error message based on the exception details.
```

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

### truncate_text()

Source: https://github.com/caentzminger/rich-raycast/blob/main/README.md

Truncates text to a specified width, adding an ellipsis if necessary.

```APIDOC
## truncate_text()

### Description
Truncates a given string to a specified maximum width. If truncation occurs, an ellipsis is appended to indicate that the text has been shortened.

### Parameters
- `text` (str): The input string to truncate.
- `width` (int): The maximum allowed width for the string.
- `ellipsis` (str): The string to append if truncation occurs. Defaults to "...".

### Returns
- `str`: The truncated string, possibly with an ellipsis.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.