### Install tzcron Package

Source: https://github.com/bloomberg/tzcron/blob/master/README.rst

Use pip to install the tzcron library.

```bash
pip install tzcron
```

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

### Create a Schedule with Start and End Times

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Create a schedule with a start and end time to generate occurrences within a specific range. Defaults to now and never if not provided.

```python
import datetime as dt
import tzcron
import pytz
now = dt.datetime.now(pytz.utc)
now_p2h = now + dt.timedelta(hours=2)
schedule = tzcron.Schedule("30 * * * * *", pytz.utc, now, now_p2h)
[s.isoformat() for s in schedule]
```

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

### tzcron Schedule with Step

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Use the step syntax (e.g., '*/X') to specify execution at intervals. This example schedules tasks every 20 minutes.

```python
>>> schedule = tzcron.Schedule("*/20 * * * * *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 2)]
['2016-09-25T22:00:00+00:00', '2016-09-25T22:20:00+00:00']
```

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

### tzcron Schedule with Month

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Specify months using their three-letter English abbreviations. This example schedules a task for days in January.

```python
>>> schedule = tzcron.Schedule("30 10 * JAN * *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 2)]
['2017-01-01T10:30:00+00:00', '2017-01-02T10:30:00+00:00']
```

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

### Valid Cron Expressions with English Keywords

Source: https://context7.com/bloomberg/tzcron/llms.txt

Examples of valid cron expressions using English keywords for weekdays and months, demonstrating case-insensitivity and correct syntax.

```python
# Valid replacement strings (English only, case insensitive)
# Weekdays: MON, TUE, WED, THU, FRI, SAT, SUN
# Months: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC

# These are all valid
valid_expressions = [
    "* * * * FRI *",      # Every Friday
    "* * * * fri *",      # Case insensitive
    "* * * JUN * *",      # Every day in June
    "* * 3 6 FRI *",      # June 3rd if it's a Friday
]
```

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

### tzcron Schedule with Multiple Values

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Provide multiple values for an option by separating them with commas. This example schedules a task for Mondays and Tuesdays.

```python
>>> schedule = tzcron.Schedule("30 10 * * mon,tue *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 3)]
['2016-09-26T10:30:00+00:00', '2016-09-27T10:30:00+00:00', '2016-10-03T10:30:00+00:00']
```

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

### Create a Schedule for a Specific Day and Time

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Create a schedule for a specific day of the month and time using a cron expression. This example generates occurrences on the first day of the month at 10:30 AM.

```python
import itertools
schedule = tzcron.Schedule("30 10 1 * * *", pytz.utc)
[s.isoformat() for s in itertools.islice(schedule, 2)]
```

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

### tzcron Schedule with Range

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Specify a range of values using a hyphen; both values are inclusive. This example schedules tasks for minutes 10 through 15.

```python
>>> schedule = tzcron.Schedule("10-15 * * * * *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 2)]
['2016-09-25T22:10:00+00:00', '2016-09-25T22:11:00+00:00']
```

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

### Create a tzcron Schedule

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Create a schedule using a cron expression and a timezone. The schedule object can be iterated to get all occurrences.

```python
import tzcron
import pytz
schedule = tzcron.Schedule("* * * * * *", pytz.utc)
str(schedule)
```

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

### Create and Iterate Schedule with Timezone

Source: https://github.com/bloomberg/tzcron/blob/master/README.rst

Instantiate a Schedule object with a cron expression and a timezone. Iterate through the schedule to get future datetime occurrences.

```python
import tzcron
import pytz
schedule = tzcron.Schedule("* * * * * *", pytz.utc)
str(schedule)
next(schedule)
next(schedule)
next(schedule)
```

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

### tzcron Schedule with Weekday

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Use the three-letter English representation for weekdays to specify a schedule. This example schedules a task for every Thursday.

```python
>>> schedule = tzcron.Schedule("30 10 * * thu *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 2)]
['2016-09-29T10:30:00+00:00', '2016-10-06T10:30:00+00:00']
```

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

### Combine Multiple Filters for Schedule Validation

Source: https://context7.com/bloomberg/tzcron/llms.txt

Apply multiple filters to a schedule; all filters must return True for an occurrence to be included. This example combines morning and even-day checks.

```python
# Multiple filters - all must pass
def is_morning(occurrence):
    return occurrence.hour < 12

def is_even_day(occurrence):
    return occurrence.day % 2 == 0

schedule = tzcron.Schedule("0 * * * * *", pytz.utc, filters=[is_morning, is_even_day])
# Returns occurrences only in morning hours on even-numbered days
```

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

### Create a Schedule in a Specific Timezone

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Create a schedule that generates occurrences in a specified timezone. The timezone of the schedule does not need to match the timezone of the start and end times.

```python
import itertools
import pytz
schedule = tzcron.Schedule("30 10 1 * * *", pytz.timezone("America/New_York"))
[s.isoformat() for s in itertools.islice(schedule, 2)]
```

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

### tzcron Schedule with Combined Specs

Source: https://github.com/bloomberg/tzcron/blob/master/docs/complex-expressions.rst

Combine various cron expression features like ranges and steps. This example schedules tasks for even minutes between 0 and 10.

```python
>>> schedule = tzcron.Schedule("0-10/2 * * * * *", pytz.utc)
>>> [s.isoformat() for s in itertools.islice(schedule, 4)]
['2016-09-25T22:00:00+00:00', '2016-09-25T22:02:00+00:00', '2016-09-25T22:04:00+00:00', '2016-09-25T22:06:00+00:00']
```

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

### Release New Package Version

Source: https://github.com/bloomberg/tzcron/blob/master/README.rst

Build and upload a new version of the package using setuptools.

```bash
python setup.py sdist bdist_wheel upload
```

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

### Safe Schedule Iteration with DST Exception Handling

Source: https://context7.com/bloomberg/tzcron/llms.txt

A robust pattern for iterating through schedules that safely skips problematic DST transition times (ambiguous or non-existent) by catching relevant pytz exceptions.

```python
# Safe pattern: wrap iteration with exception handling
def safe_schedule_iterator(schedule, max_items=10):
    """Iterate schedule, skipping DST problem times."""
    results = []
    while len(results) < max_items:
        try:
            occurrence = next(schedule)
            results.append(occurrence)
        except (pytz.AmbiguousTimeError, pytz.NonExistentTimeError):
            continue  # Skip problematic times
        except StopIteration:
            break
    return results
```

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

### Run Package Tests

Source: https://github.com/bloomberg/tzcron/blob/master/README.rst

Execute the package tests using the nose test runner.

```bash
python -m nose
```

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

### List Available Timezones with pytz

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Retrieve a list of all available timezones supported by the pytz library.

```python
import pytz
pytz.all_timezones
```

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

### Schedule job after DST change in Madrid

Source: https://github.com/bloomberg/tzcron/blob/master/docs/dst.rst

Schedules a job for 8:30 AM in Madrid, demonstrating correct handling of the DST change from +02:00 to +01:00.

```python
import datetime as dt
import pytz
import tzcron
madrid_tz = pytz.timezone("Europe/Madrid")
start_t = madrid_tz.localize(dt.datetime(2016, 10, 29))
schedule = tzcron.Schedule("30 8 * * * *", madrid_tz, start_t)
[s.isoformat() for s in itertools.islice(schedule, 2)]
```

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

### Handle non-existent time during DST forward change

Source: https://github.com/bloomberg/tzcron/blob/master/docs/dst.rst

Schedules a job for 2:30 AM in Madrid, which falls during a non-existent time due to the DST forward change. This will raise a NonExistentTimeError, requiring custom handling.

```python
start_t = madrid_tz.localize(dt.datetime(2016, 3, 26))
schedule = tzcron.Schedule("30 2 * * * *", madrid_tz, start_t)
[s.isoformat() for s in itertools.islice(schedule, 2)]
```

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

### tzcron Module Overview

Source: https://github.com/bloomberg/tzcron/blob/master/docs/api.rst

Documentation for the tzcron module, including inherited members and class inheritance structures.

```APIDOC
## tzcron Module

### Description
This module provides functionality for handling time-zone aware cron jobs. It includes all members, inherited members, and class inheritance details as defined in the source code.

### Members
- Includes all public members, undocumented members, and inherited members from base classes.

### Inheritance
- The module documentation includes full class inheritance diagrams and structures.
```

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

### Handling Non-Existent Times During DST Spring Forward

Source: https://context7.com/bloomberg/tzcron/llms.txt

Catch pytz.NonExistentTimeError when scheduling during DST spring forward, where a time does not exist. Implement custom logic to handle skipped occurrences.

```python
# Handling non-existent times (clocks spring forward - time doesn't exist)
start_spring = madrid_tz.localize(dt.datetime(2016, 3, 26))
try:
    schedule = tzcron.Schedule("30 2 * * * *", madrid_tz, start_spring)
    next(schedule)
except pytz.NonExistentTimeError as e:
    print(f"Non-existent time: {e}")
    # Handle skipped occurrence according to business logic
```

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

### Create and Iterate Time Schedules

Source: https://context7.com/bloomberg/tzcron/llms.txt

The Schedule class is the primary interface for defining cron-based schedules with specific timezones and optional start/end constraints.

```python
import datetime as dt
import itertools
import tzcron
import pytz

# Basic schedule - every minute in UTC
schedule = tzcron.Schedule("* * * * * *", pytz.utc)
print(str(schedule))
# Output: 'Cron: * * * * * * @UTC [2024-01-15 10:30:00.123456+00:00->None]'

# Get next occurrences by iterating
print(next(schedule))  # datetime.datetime(2024, 1, 15, 10, 31, tzinfo=<UTC>)
print(next(schedule))  # datetime.datetime(2024, 1, 15, 10, 32, tzinfo=<UTC>)

# Schedule with start and end dates - occurrences at minute 30 in a 2-hour window
now = dt.datetime.now(pytz.utc)
end_time = now + dt.timedelta(hours=2)
schedule = tzcron.Schedule("30 * * * * *", pytz.utc, now, end_time)
occurrences = [s.isoformat() for s in schedule]
print(occurrences)
# Output: ['2024-01-15T11:30:00+00:00', '2024-01-15T12:30:00+00:00']

# Schedule with specific timezone - daily at 8:30 AM New York time
ny_tz = pytz.timezone("America/New_York")
schedule = tzcron.Schedule("30 8 * * * *", ny_tz)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 3)]
print(occurrences)
# Output: ['2024-01-15T08:30:00-05:00', '2024-01-16T08:30:00-05:00', '2024-01-17T08:30:00-05:00']

# First day of each month at 10:30 AM
schedule = tzcron.Schedule("30 10 1 * * *", pytz.utc)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 3)]
print(occurrences)
# Output: ['2024-02-01T10:30:00+00:00', '2024-03-01T10:30:00+00:00', '2024-04-01T10:30:00+00:00']
```

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

### Define and apply a custom schedule filter

Source: https://github.com/bloomberg/tzcron/blob/master/docs/filters.rst

Create a filter function that returns a boolean to validate occurrences, then pass it to the schedule constructor.

```python
>>> def is_funny_date(occurrence):
...     return occurrence.minute == occurrence.hour
...
>>> schedule = tzcron.Schedule("* * * * * *", pytz.utc, filters=[is_funny_date])
>>> [s.isoformat() for s in itertools.islice(schedule, 2)]
['2016-09-25T22:22:00+00:00', '2016-09-25T23:23:00+00:00']
```

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

### Define Cron Expressions

Source: https://context7.com/bloomberg/tzcron/llms.txt

Utilize 6-field cron expressions to define complex schedules including wildcards, ranges, steps, and named day/month values.

```python
import tzcron
import pytz
import itertools

# Cron expression format:
# * * * * * *
# | | | | | |
# | | | | | year (yyyy or * for any)
# | | | | day of week (1-7, Monday=1 to Sunday=7, or MON-SUN)
# | | | month (1-12 or JAN-DEC)
# | | day of month (1-31)
# | hour (0-23)
# minute (0-59)

# Every Friday at 5:00 AM
schedule = tzcron.Schedule("0 5 * * 5 *", pytz.utc)

# Using string replacements - every Thursday at 10:30
schedule = tzcron.Schedule("30 10 * * thu *", pytz.utc)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 2)]
print(occurrences)
# Output: ['2024-01-18T10:30:00+00:00', '2024-01-25T10:30:00+00:00']

# Every day in January at 10:30 (case insensitive)
schedule = tzcron.Schedule("30 10 * JAN * *", pytz.utc)

# Specific year - all occurrences in 2025
schedule = tzcron.Schedule("0 12 1 * * 2025", pytz.utc)

# Multiple values - Mondays and Tuesdays at 10:30
schedule = tzcron.Schedule("30 10 * * mon,tue *", pytz.utc)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 4)]
print(occurrences)
# Output: ['2024-01-15T10:30:00+00:00', '2024-01-16T10:30:00+00:00',
#          '2024-01-22T10:30:00+00:00', '2024-01-23T10:30:00+00:00']

# Ranges - minutes 10 through 15
schedule = tzcron.Schedule("10-15 * * * * *", pytz.utc)

# Steps - every 20 minutes
schedule = tzcron.Schedule("*/20 * * * * *", pytz.utc)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 3)]
print(occurrences)
# Output: ['2024-01-15T11:00:00+00:00', '2024-01-15T11:20:00+00:00', '2024-01-15T11:40:00+00:00']

# Combined - even minutes between 0 and 10
schedule = tzcron.Schedule("0-10/2 * * * * *", pytz.utc)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 6)]
print(occurrences)
# Output: ['2024-01-15T11:00:00+00:00', '2024-01-15T11:02:00+00:00',
#          '2024-01-15T11:04:00+00:00', '2024-01-15T11:06:00+00:00',
#          '2024-01-15T11:08:00+00:00', '2024-01-15T11:10:00+00:00']
```

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

### Handle ambiguous time during DST backward change

Source: https://github.com/bloomberg/tzcron/blob/master/docs/dst.rst

Schedules a job for 2:30 AM in Madrid, which falls during an ambiguous time due to the DST backward change. This will raise an AmbiguousTimeError, requiring custom handling.

```python
madrid_tz = pytz.timezone("Europe/Madrid")
start_t = madrid_tz.localize(dt.datetime(2016, 10, 29))
schedule = tzcron.Schedule("30 2 * * * *", madrid_tz, start_t)
[s.isoformat() for s in itertools.islice(schedule, 2)]
```

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

### DST-Aware Scheduling with Offset Adjustments

Source: https://context7.com/bloomberg/tzcron/llms.txt

Schedule events in a DST-aware timezone. tzcron automatically adjusts offsets during DST transitions, as shown with Madrid time across an October change.

```python
import datetime as dt
import tzcron
import pytz
import itertools

# DST-aware scheduling - times automatically adjust offsets
madrid_tz = pytz.timezone("Europe/Madrid")
start = madrid_tz.localize(dt.datetime(2016, 10, 29))

# Schedule at 8:30 AM Madrid time across DST change (Oct 30, 2016)
schedule = tzcron.Schedule("30 8 * * * *", madrid_tz, start)
occurrences = [s.isoformat() for s in itertools.islice(schedule, 2)]
print(occurrences)
# Output: ['2016-10-29T08:30:00+02:00', '2016-10-30T08:30:00+01:00']
# Note: offset changes from +02:00 to +01:00 due to DST end
```

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

### Filter Occurrences by Minute Equals Hour

Source: https://context7.com/bloomberg/tzcron/llms.txt

Use custom filter functions to include only occurrences where the minute matches the hour. Requires importing tzcron, pytz, and itertools.

```python
import tzcron
import pytz
import itertools

# Filter function: only include occurrences where minute equals hour
def is_funny_date(occurrence):
    return occurrence.minute == occurrence.hour

schedule = tzcron.Schedule("* * * * * *", pytz.utc, filters=[is_funny_date])
occurrences = [s.isoformat() for s in itertools.islice(schedule, 3)]
print(occurrences)
# Output: ['2024-01-15T11:11:00+00:00', '2024-01-15T12:12:00+00:00', '2024-01-15T13:13:00+00:00']
```

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

### Catching Invalid Cron Expression Parsing Errors

Source: https://context7.com/bloomberg/tzcron/llms.txt

Demonstrates how to catch the tzcron.InvalidExpression exception for various malformed cron expressions, including empty strings and out-of-range values.

```python
import tzcron
import pytz

timezone = pytz.utc
now = pytz.utc.localize(__import__('datetime').datetime.now())

# Invalid expressions that raise InvalidExpression
invalid_expressions = [
    "",                    # Empty expression
    "-1 1 * * * *",       # Negative minute
    "60 * * * * *",       # Minute out of range (0-59)
    "* 24 * * * *",       # Hour out of range (0-23)
    "* * 32 * * *",       # Day of month out of range (1-31)
    "* * * 13 * *",       # Month out of range (1-12)
    "* * * * 8 *",        # Weekday out of range (1-7)
    "* * * * 0 *",        # Weekday 0 is invalid (use 7 for Sunday)
    "* * * LUN * *",      # Invalid replacement (Spanish not supported)
]

for expr in invalid_expressions:
    try:
        schedule = tzcron.Schedule(expr, timezone, now)
    except tzcron.InvalidExpression as e:
        print(f"Invalid: '{expr}' - {e}")
```

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

### Filter to Stop Iteration After a Condition

Source: https://context7.com/bloomberg/tzcron/llms.txt

Create a filter that raises StopIteration to halt the schedule iteration once a specific condition is met, such as passing a certain hour.

```python
# Filter that stops iteration after a condition
def stop_after_noon(occurrence):
    if occurrence.hour >= 12:
        raise StopIteration("Past noon")
    return True
```

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

### Handling Ambiguous Times During DST Fallback

Source: https://context7.com/bloomberg/tzcron/llms.txt

Catch pytz.AmbiguousTimeError when scheduling during DST fallback, where a time occurs twice. The iterator advances after the exception.

```python
# Handling ambiguous times (clocks fall back - time occurs twice)
try:
    schedule = tzcron.Schedule("30 2 * * * *", madrid_tz, start)
    next(schedule)
except pytz.AmbiguousTimeError as e:
    print(f"Ambiguous time: {e}")
    # Handle the ambiguous occurrence according to business logic
    # The iterator advances, so next call returns the following occurrence
```

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

### Iterate Over Schedule Occurrences

Source: https://github.com/bloomberg/tzcron/blob/master/docs/basic-usage.rst

Iterate over a tzcron schedule object to retrieve all occurrences of the specified schedule.

```python
next(schedule)
```

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

### Filter Occurrences by Weekday

Source: https://context7.com/bloomberg/tzcron/llms.txt

Implement a filter to include only weekday occurrences. The filter function checks the occurrence's weekday attribute.

```python
# Business day filter example
def is_weekday(occurrence):
    # Monday=0, Sunday=6 in Python's weekday()
    return occurrence.weekday() < 5  # Monday to Friday only

schedule = tzcron.Schedule("0 9 * * * *", pytz.utc, filters=[is_weekday])
# Returns only weekday occurrences at 9:00 AM
```

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