Skip to content

PFR SDK

Pro Football Reference HTML scraping client.

pfr

AsyncScrapingBackend

Bases: Protocol

Protocol for asynchronous HTML scraping backends.

Implementations must provide an async get_page_content method that fetches a fully-rendered web page and returns its HTML as a string.

get_page_content async 

get_page_content(url, wait_for_element)

Fetch a page's HTML content asynchronously.

Parameters:

Name Type Description Default
url str

The full URL to fetch.

 required
wait_for_element str

CSS selector to wait for before extracting HTML.

 required

Returns:

Type Description
str

The page's outer HTML as a string.
Source code in src/griddy/pfr/backends.py 
52
53
54
55
56
57
58
59
60
61
62
async def get_page_content(self, url: str, wait_for_element: str) -> str:
    """Fetch a page's HTML content asynchronously.

    Args:
        url: The full URL to fetch.
        wait_for_element: CSS selector to wait for before extracting HTML.

    Returns:
        The page's outer HTML as a string.
    """
    ...

ScrapingBackend

Bases: Protocol

Protocol for synchronous HTML scraping backends.

Implementations must provide a get_page_content method that fetches a fully-rendered web page and returns its HTML as a string.

get_page_content 

get_page_content(url, wait_for_element)

Fetch a page's HTML content.

Parameters:

Name Type Description Default
url str

The full URL to fetch.

 required
wait_for_element str

CSS selector to wait for before extracting HTML.

 required

Returns:

Type Description
str

The page's outer HTML as a string.
Source code in src/griddy/pfr/backends.py 
31
32
33
34
35
36
37
38
39
40
41
def get_page_content(self, url: str, wait_for_element: str) -> str:
    """Fetch a page's HTML content.

    Args:
        url: The full URL to fetch.
        wait_for_element: CSS selector to wait for before extracting HTML.

    Returns:
        The page's outer HTML as a string.
    """
    ...

GriddyPFR 

GriddyPFR(
    pfr_auth=None,
    server_idx=None,
    server_url=None,
    url_params=None,
    client=None,
    async_client=None,
    retry_config=UNSET,
    timeout_ms=None,
    debug_logger=None,
    browserless_config=None,
    scraping_backend=None,
    async_scraping_backend=None,
)

Bases: LazySubSDKMixin, BaseGriddySDK, BaseSDK

Main client for accessing Pro Football Reference data.

Sub-SDKs are loaded lazily on first access to minimize startup time.

Example

from griddy.pfr import GriddyPFR pfr = GriddyPFR() games = pfr.schedule.get_season_schedule(season=2015)

Parameters:

Name Type Description Default
pfr_auth Optional[Dict[str, str]]

Optional dictionary containing authentication information. PFR does not currently require auth, but this is available for future use. Example: {"accessToken": "your_token"}

 None
server_idx Optional[int]

Index of the server to use from the server list.

 None
server_url Optional[str]

Override the default server URL.

 None
url_params Optional[Dict[str, str]]

Parameters to template into the server URL.

 None
client Optional[HttpClient]

Custom synchronous HTTP client (must implement HttpClient).

 None
async_client Optional[AsyncHttpClient]

Custom async HTTP client (must implement AsyncHttpClient).

 None
retry_config OptionalNullable[RetryConfig]

Configuration for automatic request retries.

 UNSET
timeout_ms Optional[int]

Request timeout in milliseconds.

 None
debug_logger Optional[Logger]

Custom logger for debug output.

 None
browserless_config Optional[BrowserlessConfig]

Configuration for Browserless API requests. Overrides default proxy, timeout, and TTL values. Ignored when a custom scraping_backend is provided.

 None
scraping_backend Optional[ScrapingBackend]

A synchronous scraping backend that satisfies the :class:~griddy.pfr.backends.ScrapingBackend protocol. When provided, this backend is used instead of the default Browserless client.

 None
async_scraping_backend Optional[AsyncScrapingBackend]

An asynchronous scraping backend that satisfies the :class:~griddy.pfr.backends.AsyncScrapingBackend protocol. When provided, this backend is used instead of the default async Browserless client.

 None
Source code in src/griddy/pfr/sdk.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def __init__(
    self,
    pfr_auth: Optional[Dict[str, str]] = None,
    server_idx: Optional[int] = None,
    server_url: Optional[str] = None,
    url_params: Optional[Dict[str, str]] = None,
    client: Optional[HttpClient] = None,
    async_client: Optional[AsyncHttpClient] = None,
    retry_config: OptionalNullable[RetryConfig] = UNSET,
    timeout_ms: Optional[int] = None,
    debug_logger: Optional[Logger] = None,
    browserless_config: Optional[BrowserlessConfig] = None,
    scraping_backend: Optional[ScrapingBackend] = None,
    async_scraping_backend: Optional[AsyncScrapingBackend] = None,
) -> None:
    """Initialize the GriddyPFR client.

    Args:
        pfr_auth: Optional dictionary containing authentication information.
            PFR does not currently require auth, but this is available for
            future use. Example: {"accessToken": "your_token"}
        server_idx: Index of the server to use from the server list.
        server_url: Override the default server URL.
        url_params: Parameters to template into the server URL.
        client: Custom synchronous HTTP client (must implement HttpClient).
        async_client: Custom async HTTP client (must implement AsyncHttpClient).
        retry_config: Configuration for automatic request retries.
        timeout_ms: Request timeout in milliseconds.
        debug_logger: Custom logger for debug output.
        browserless_config: Configuration for Browserless API requests.
            Overrides default proxy, timeout, and TTL values. Ignored when
            a custom *scraping_backend* is provided.
        scraping_backend: A synchronous scraping backend that satisfies the
            :class:`~griddy.pfr.backends.ScrapingBackend` protocol. When
            provided, this backend is used instead of the default
            Browserless client.
        async_scraping_backend: An asynchronous scraping backend that
            satisfies the :class:`~griddy.pfr.backends.AsyncScrapingBackend`
            protocol. When provided, this backend is used instead of the
            default async Browserless client.
    """
    # Pre-set so PFR BaseSDK.__init__ can pick it up via getattr
    # (MRO super().__init__ doesn't forward extra kwargs).
    self._browserless_config = browserless_config
    self._scraping_backend = scraping_backend
    self._async_scraping_backend = async_scraping_backend
    self._init_sdk(
        auth=pfr_auth,
        server_idx=server_idx,
        server_url=server_url,
        url_params=url_params,
        client=client,
        async_client=async_client,
        retry_config=retry_config,
        timeout_ms=timeout_ms,
        debug_logger=debug_logger,
        scraping_backend=scraping_backend,
        async_scraping_backend=async_scraping_backend,
    )

SDKConfiguration dataclass 

SDKConfiguration(
    client,
    client_supplied,
    async_client,
    async_client_supplied,
    debug_logger,
    security=None,
    server_url="",
    server_idx=0,
    language="python",
    sdk_version=__version__,
    user_agent=__user_agent__,
    retry_config=(lambda: UNSET)(),
    timeout_ms=None,
    server_type="default",
    scraping_backend=None,
    async_scraping_backend=None,
)

Bases: SDKConfiguration

PFR-specific SDK configuration with server URL resolution.

get_server_details 

get_server_details()

Return the base URL and params for the configured server type.

Source code in src/griddy/pfr/sdkconfiguration.py 
29
30
31
32
33
34
35
def get_server_details(self) -> Tuple[str, Dict[str, str]]:
    """Return the base URL and params for the configured server type."""
    if self.server_url is not None and self.server_url:
        return remove_suffix(self.server_url, "/"), {}

    server_url = SERVERS.get(self.server_type, SERVERS["default"])
    return server_url, {}