Skip to content

Utilities

nflreadpy.get_current_season 

get_current_season(roster: bool = False) -> int

Get the current NFL season year.

Parameters:

Name Type Description Default
roster bool
  • If True, uses roster year logic (current year after March 15).
  • If False, uses season logic (current year after Thursday following Labor Day).
 False

Returns:

Type Description
int

The current season/roster year.
See Also

https://nflreadr.nflverse.com/reference/get_current_season.html

Source code in src/nflreadpy/utils_date.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def get_current_season(roster: bool = False) -> int:
    """
    Get the current NFL season year.

    Args:
        roster:
            - If True, uses roster year logic (current year after March 15).
            - If False, uses season logic (current year after Thursday following Labor Day).

    Returns:
        The current season/roster year.

    See Also:
        <https://nflreadr.nflverse.com/reference/get_current_season.html>
    """
    if not isinstance(roster, bool):
        raise TypeError("argument `roster` must be boolean")

    today = date.today()
    current_year = today.year

    if roster:
        # Roster logic: current year after March 15, otherwise previous year
        march_15 = date(current_year, 3, 15)
        return current_year if today >= march_15 else current_year - 1
    else:
        # Season logic: current year after Thursday following Labor Day
        # Labor Day is first Monday in September
        # Find first Monday in September
        for day in range(1, 8):
            if date(current_year, 9, day).weekday() == 0:  # Monday
                labor_day = date(current_year, 9, day)
                break

        # Thursday following Labor Day
        season_start = date(labor_day.year, labor_day.month, labor_day.day + 3)
        return current_year if today >= season_start else current_year - 1

nflreadpy.get_current_week 

get_current_week(use_date: bool = False, **kwargs) -> int

Get the current NFL week (rough approximation).

Parameters:

Name Type Description Default
use_date bool
  • If True, calculates week as the number of weeks since Thursday following Labor Day.
  • If False, loads schedules via load_schedules(seasons = get_current_season(**kwargs)) and returns week of the next game.
 False
**kwargs

Arguments passed on to get_current_season()

 {}

Returns:

Type Description
int

The current NFL week (1-22).
See Also

https://nflreadr.nflverse.com/reference/get_current_week.html

Source code in src/nflreadpy/utils_date.py 
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_current_week(use_date: bool = False, **kwargs) -> int:
    """
    Get the current NFL week (rough approximation).

    Args:
        use_date:
            - If `True`, calculates week as the number of weeks since Thursday following Labor Day.
            - If `False`, loads schedules via `load_schedules(seasons = get_current_season(**kwargs))` and returns week of the next game.
        **kwargs:
            Arguments passed on to `get_current_season()`

    Returns:
        The current NFL week (1-22).

    See Also:
        <https://nflreadr.nflverse.com/reference/get_current_week.html>
    """
    if not isinstance(use_date, bool):
        raise TypeError("argument `use_date` must be boolean")

    from .load_schedules import load_schedules

    if use_date:
        today = date.today()
        season_year = get_current_season(**kwargs)

        # NFL season typically starts around first Thursday of September
        # Find first Thursday in September
        for day in range(1, 8):
            if date(season_year, 9, day).weekday() == 3:  # Thursday
                season_start = date(season_year, 9, day)
                break

        if today < season_start:
            return 1

        # Calculate weeks since season start
        days_since_start = (today - season_start).days
        week = min(days_since_start // 7 + 1, 22)  # Cap at week 22

        return int(week)
    else:
        sched = load_schedules(seasons=get_current_season(**kwargs))
        count_na_weeks = sched.select("result").null_count().item()
        if count_na_weeks == 0:
            # no NA values in result, return max(week)
            return sched.select("week").drop_nulls().max().item()
        else:
            # there are NA values in result. Filter table to NA results only,
            # and return min(week)
            return (
                sched.filter(pl.col("result").is_null())
                .select("week")
                .drop_nulls()
                .min()
                .item()
            )