fastnascar 0.1.0__tar.gz

fastnascar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FastNASCAR contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastnascar-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE pyproject.toml
+recursive-include src *.py
+recursive-include examples *.py *.ps1
+recursive-include tests *.py *.json *.md
+prune build
+prune dist
+prune outputs
+prune .plot-deps
+prune .matplotlib
+prune .fastnascar-cache
+prune .release-tools
+prune .release-install
+global-exclude __pycache__ *.py[cod]

fastnascar-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: fastnascar
+Version: 0.1.0
+Summary: Pandas-based NASCAR sessions, laps, results, and live timing
+License-Expression: MIT
+Keywords: nascar,motorsport,timing,pandas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<4,>=2.2
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# FastNASCAR
+
+FastNASCAR provides NASCAR Cup lap times, results, and live timing in pandas.
+Select a race, load the session, and work with its lap data:
+
+```python
+import fastnascar
+
+session = fastnascar.get_session(2026, race_id=5626).load()
+hocevar = session.laps.pick_driver("77")
+print(hocevar.pick_fastest())
+```
+
+Early release. Race laps and weekend results work; historical practice and
+qualifying laps aren't supported yet. No throttle, brake, RPM, or GPS telemetry.
+This project is unaffiliated with NASCAR.
+
+## Install
+
+Python 3.10+ is required. From a checkout:
+
+```sh
+python -m pip install -e .
+python -m pip install -e ".[plot]"  # optional matplotlib charts
+```
+
+## Pick a race
+
+```python
+schedule = fastnascar.get_event_schedule(2026)
+print(schedule[["RoundNumber", "RaceId", "EventName", "EventDate"]])
+
+session = fastnascar.get_session(2026, 29)
+session = fastnascar.get_session(2026, "Bass Pro Shops Night Race")
+session = fastnascar.get_session(2026, race_id=5626)
+session.load()
+```
+
+Rounds count points races in scheduled order. Use
+`include_exhibition=True` to include exhibitions in the schedule; select those
+by name or race ID. Repeated names raise `AmbiguousEventError`, with the matching
+race IDs. Schedule dates retain NASCAR's local timestamps without a timezone.
+
+## Work with laps
+
+```python
+hocevar = session.laps.pick_driver("77")
+print(hocevar.pick_fastest())
+print(hocevar.pick_laps([1, 2, 3]))
+print(hocevar.pick_quicklaps().LapTime.dt.total_seconds().mean())
+print(session.results[["Position", "DriverNumber", "FullName", "Points"]])
+```
+
+| Table | Columns |
+| --- | --- |
+| `session.laps` | Driver, DriverNumber, DriverId, LapNumber, LapTime, Speed, Position |
+| `session.results` | DriverNumber, DriverId, FullName, TeamName, Manufacturer, Position, GridPosition, Laps, LapsLed, Points, Status, BestLapTime |
+| `session.track_status` | LeaderLapNumber, FlagState |
+
+Lap times are pandas timedeltas. Speeds are lap-average mph. Car numbers are
+strings; missing values stay missing. Lap zero is excluded because it records
+the starting order.
+
+`pick_drivers()` accepts one or more car numbers or exact full names.
+`pick_quicklaps(1.07)` keeps times below 107% of the fastest lap in the current
+selection. Select a driver first to use that driver's pace. The filter doesn't
+identify cautions or pit laps.
+
+Flags refer to leader laps and stay separate from car laps. A lapped car's lap
+number doesn't line up with the leader's. FlagState contains raw feed codes.
+
+## Practice and qualifying
+
+```python
+practice = fastnascar.get_session(2026, race_id=5626, identifier="P")
+practice.load(laps=False)
+qualifying = fastnascar.get_session(2026, race_id=5626, identifier="Q")
+qualifying.load(laps=False)
+```
+
+These sessions provide results and best lap times. When a weekend has several
+runs of the same type, pass the exact `run_name` from the weekend feed.
+Qualifying results may cover only the final round.
+
+## Plot a race
+
+```python
+from fastnascar.plotting import plot_lap_times
+import matplotlib.pyplot as plt
+
+plot_lap_times(session.laps, drivers=["77", "5"])
+plt.show()
+```
+
+The Bristol example saves a full-race chart, a pace detail view, and a CSV:
+
+```sh
+python examples/hocevar_bristol_2026.py
+python examples/hocevar_bristol_2026.py --race spring --show
+```
+
+The default is the September 19, 2026 night race. Files go into `outputs/`.
+On Windows, `examples/hocevar_bristol_2026.ps1` also runs the script using
+an available Python installation or the bundled desktop runtime.
+
+## Live timing
+
+```python
+import fastnascar
+
+snapshot = fastnascar.get_live_session()
+print(snapshot.timing)
+print(snapshot.pit_stops)
+
+for snapshot in fastnascar.iter_live(interval=2, max_updates=10):
+    print(snapshot.timestamp)
+    print(snapshot.timing.query("DriverNumber == '77'"))
+```
+
+The live feed serves the currently active session. It can't replay an earlier
+race. Requests bypass the cache. Updates can repeat or become stale; check the
+source timestamp. Pass `race_id=...` to require a specific race.
+
+Polling raises an error if the feed switches race, timing run, or series.
+The default delay is two seconds, with a minimum of one second. LastLapTime
+and ElapsedTime are timedeltas; gaps and status retain the feed's values.
+Polling can miss laps between updates.
+
+Record and replay snapshots:
+
+```python
+fastnascar.record_live("race.jsonl", interval=2, max_updates=100)
+for snapshot in fastnascar.replay_live("race.jsonl"):
+    print(snapshot.timestamp, snapshot.timing.head())
+```
+
+Recordings append to the file and flush after each update. Replay runs offline.
+
+## Cache
+
+```python
+fastnascar.Cache.enable_cache(".fastnascar-cache")
+session = fastnascar.get_session(2026, race_id=5626).load()
+
+# Reuse downloaded data without network access.
+fastnascar.Cache.enable_cache(".fastnascar-cache", offline=True)
+session = fastnascar.get_session(2026, race_id=5626).load()
+```
+
+Settings apply across the process. Cached responses expire after an hour.
+`refresh=True` on `load()` fetches new data. Offline mode accepts old entries
+and raises on a cache miss, including live requests.
+`Cache.disable_cache()` restores network access without deleting files;
+`Cache.clear_cache()` removes this package's cached responses.
+
+Unavailable feeds raise `DataNotAvailableError`; unsupported schemas raise
+`InvalidDataError`. Accessing a table before loading it raises
+`SessionNotLoadedError`. A failed reload keeps the previous session tables.
+Function docstrings describe arguments, return values, and errors.
+
+## Data
+
+Feeds are hosted at `https://cf.nascar.com`:
+
+- Schedule: `cacher/{year}/race_list_basic.json`
+- Results: `cacher/{year}/1/{race_id}/weekend-feed.json`
+- Race laps and flags: `cacher/{year}/1/{race_id}/lap-times.json`
+- Live timing: `live/feeds/live-feed.json`
+
+Coverage depends on what NASCAR makes available. Verified examples include
+the 2024 Food City 500, the 2026 Bristol night race, and Cup live timing.
+Feed URLs and schemas can change.
+
+Code is MIT licensed. NASCAR feed data and test excerpts aren't covered by
+that license.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+Tests run offline with recorded feed excerpts and mocked requests. Examples
+make real requests. CI runs the tests on Python 3.10, 3.12, and 3.13.

fastnascar-0.1.0/README.md

@@ -0,0 +1,187 @@
+# FastNASCAR
+
+FastNASCAR provides NASCAR Cup lap times, results, and live timing in pandas.
+Select a race, load the session, and work with its lap data:
+
+```python
+import fastnascar
+
+session = fastnascar.get_session(2026, race_id=5626).load()
+hocevar = session.laps.pick_driver("77")
+print(hocevar.pick_fastest())
+```
+
+Early release. Race laps and weekend results work; historical practice and
+qualifying laps aren't supported yet. No throttle, brake, RPM, or GPS telemetry.
+This project is unaffiliated with NASCAR.
+
+## Install
+
+Python 3.10+ is required. From a checkout:
+
+```sh
+python -m pip install -e .
+python -m pip install -e ".[plot]"  # optional matplotlib charts
+```
+
+## Pick a race
+
+```python
+schedule = fastnascar.get_event_schedule(2026)
+print(schedule[["RoundNumber", "RaceId", "EventName", "EventDate"]])
+
+session = fastnascar.get_session(2026, 29)
+session = fastnascar.get_session(2026, "Bass Pro Shops Night Race")
+session = fastnascar.get_session(2026, race_id=5626)
+session.load()
+```
+
+Rounds count points races in scheduled order. Use
+`include_exhibition=True` to include exhibitions in the schedule; select those
+by name or race ID. Repeated names raise `AmbiguousEventError`, with the matching
+race IDs. Schedule dates retain NASCAR's local timestamps without a timezone.
+
+## Work with laps
+
+```python
+hocevar = session.laps.pick_driver("77")
+print(hocevar.pick_fastest())
+print(hocevar.pick_laps([1, 2, 3]))
+print(hocevar.pick_quicklaps().LapTime.dt.total_seconds().mean())
+print(session.results[["Position", "DriverNumber", "FullName", "Points"]])
+```
+
+| Table | Columns |
+| --- | --- |
+| `session.laps` | Driver, DriverNumber, DriverId, LapNumber, LapTime, Speed, Position |
+| `session.results` | DriverNumber, DriverId, FullName, TeamName, Manufacturer, Position, GridPosition, Laps, LapsLed, Points, Status, BestLapTime |
+| `session.track_status` | LeaderLapNumber, FlagState |
+
+Lap times are pandas timedeltas. Speeds are lap-average mph. Car numbers are
+strings; missing values stay missing. Lap zero is excluded because it records
+the starting order.
+
+`pick_drivers()` accepts one or more car numbers or exact full names.
+`pick_quicklaps(1.07)` keeps times below 107% of the fastest lap in the current
+selection. Select a driver first to use that driver's pace. The filter doesn't
+identify cautions or pit laps.
+
+Flags refer to leader laps and stay separate from car laps. A lapped car's lap
+number doesn't line up with the leader's. FlagState contains raw feed codes.
+
+## Practice and qualifying
+
+```python
+practice = fastnascar.get_session(2026, race_id=5626, identifier="P")
+practice.load(laps=False)
+qualifying = fastnascar.get_session(2026, race_id=5626, identifier="Q")
+qualifying.load(laps=False)
+```
+
+These sessions provide results and best lap times. When a weekend has several
+runs of the same type, pass the exact `run_name` from the weekend feed.
+Qualifying results may cover only the final round.
+
+## Plot a race
+
+```python
+from fastnascar.plotting import plot_lap_times
+import matplotlib.pyplot as plt
+
+plot_lap_times(session.laps, drivers=["77", "5"])
+plt.show()
+```
+
+The Bristol example saves a full-race chart, a pace detail view, and a CSV:
+
+```sh
+python examples/hocevar_bristol_2026.py
+python examples/hocevar_bristol_2026.py --race spring --show
+```
+
+The default is the September 19, 2026 night race. Files go into `outputs/`.
+On Windows, `examples/hocevar_bristol_2026.ps1` also runs the script using
+an available Python installation or the bundled desktop runtime.
+
+## Live timing
+
+```python
+import fastnascar
+
+snapshot = fastnascar.get_live_session()
+print(snapshot.timing)
+print(snapshot.pit_stops)
+
+for snapshot in fastnascar.iter_live(interval=2, max_updates=10):
+    print(snapshot.timestamp)
+    print(snapshot.timing.query("DriverNumber == '77'"))
+```
+
+The live feed serves the currently active session. It can't replay an earlier
+race. Requests bypass the cache. Updates can repeat or become stale; check the
+source timestamp. Pass `race_id=...` to require a specific race.
+
+Polling raises an error if the feed switches race, timing run, or series.
+The default delay is two seconds, with a minimum of one second. LastLapTime
+and ElapsedTime are timedeltas; gaps and status retain the feed's values.
+Polling can miss laps between updates.
+
+Record and replay snapshots:
+
+```python
+fastnascar.record_live("race.jsonl", interval=2, max_updates=100)
+for snapshot in fastnascar.replay_live("race.jsonl"):
+    print(snapshot.timestamp, snapshot.timing.head())
+```
+
+Recordings append to the file and flush after each update. Replay runs offline.
+
+## Cache
+
+```python
+fastnascar.Cache.enable_cache(".fastnascar-cache")
+session = fastnascar.get_session(2026, race_id=5626).load()
+
+# Reuse downloaded data without network access.
+fastnascar.Cache.enable_cache(".fastnascar-cache", offline=True)
+session = fastnascar.get_session(2026, race_id=5626).load()
+```
+
+Settings apply across the process. Cached responses expire after an hour.
+`refresh=True` on `load()` fetches new data. Offline mode accepts old entries
+and raises on a cache miss, including live requests.
+`Cache.disable_cache()` restores network access without deleting files;
+`Cache.clear_cache()` removes this package's cached responses.
+
+Unavailable feeds raise `DataNotAvailableError`; unsupported schemas raise
+`InvalidDataError`. Accessing a table before loading it raises
+`SessionNotLoadedError`. A failed reload keeps the previous session tables.
+Function docstrings describe arguments, return values, and errors.
+
+## Data
+
+Feeds are hosted at `https://cf.nascar.com`:
+
+- Schedule: `cacher/{year}/race_list_basic.json`
+- Results: `cacher/{year}/1/{race_id}/weekend-feed.json`
+- Race laps and flags: `cacher/{year}/1/{race_id}/lap-times.json`
+- Live timing: `live/feeds/live-feed.json`
+
+Coverage depends on what NASCAR makes available. Verified examples include
+the 2024 Food City 500, the 2026 Bristol night race, and Cup live timing.
+Feed URLs and schemas can change.
+
+Code is MIT licensed. NASCAR feed data and test excerpts aren't covered by
+that license.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+Tests run offline with recorded feed excerpts and mocked requests. Examples
+make real requests. CI runs the tests on Python 3.10, 3.12, and 3.13.

fastnascar-0.1.0/examples/analyze_race.py

@@ -0,0 +1,9 @@
+"""Run after installing: python examples/analyze_race.py"""
+import fastnascar
+
+fastnascar.Cache.enable_cache(".fastnascar-cache")
+session = fastnascar.get_session(2024, race_id=5392).load()
+print(session.results[["Position", "DriverNumber", "FullName", "Points"]].head(10))
+hamlin = session.laps.pick_driver("11")
+print(hamlin.pick_fastest())
+print(hamlin.pick_quicklaps().LapTime.dt.total_seconds().describe())

fastnascar-0.1.0/examples/hocevar_bristol_2026.ps1

@@ -0,0 +1,26 @@
+# Run from PowerShell: .\examples\hocevar_bristol_2026.ps1
+# Pass Python script options, for example: --race spring --show
+$taskRoot = Split-Path $PSScriptRoot -Parent
+$taskPython = Get-Command python -ErrorAction SilentlyContinue
+$taskBundledPython = Join-Path $env:USERPROFILE '.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe'
+if ($taskPython) {
+    $taskPythonPath = $taskPython.Source
+} elseif (Test-Path -LiteralPath $taskBundledPython) {
+    $taskPythonPath = $taskBundledPython
+} else {
+    throw 'Python is required. Install Python 3.10 or newer and the package with its plot extra.'
+}
+$taskOldPythonPath = $env:PYTHONPATH
+$taskOldMplConfig = $env:MPLCONFIGDIR
+try {
+    $taskPlotDeps = Join-Path $taskRoot '.plot-deps'
+    if (Test-Path -LiteralPath $taskPlotDeps) {
+        $env:PYTHONPATH = "$taskPlotDeps;$taskOldPythonPath"
+    }
+    $env:MPLCONFIGDIR = Join-Path $taskRoot '.matplotlib'
+    & $taskPythonPath (Join-Path $PSScriptRoot 'hocevar_bristol_2026.py') @args
+    if ($LASTEXITCODE -ne 0) { throw "Chart script failed with exit code $LASTEXITCODE" }
+} finally {
+    $env:PYTHONPATH = $taskOldPythonPath
+    $env:MPLCONFIGDIR = $taskOldMplConfig
+}

fastnascar-0.1.0/examples/hocevar_bristol_2026.py

@@ -0,0 +1,123 @@
+"""Chart Carson Hocevar's lap times at Bristol in 2026 using real NASCAR data.
+
+From the repository root:
+    python -m pip install -e ".[plot]"
+    python examples/hocevar_bristol_2026.py
+    python examples/hocevar_bristol_2026.py --race spring --show
+
+The default is the September 19 Bass Pro Shops Night Race (race ID 5626).
+"""
+import argparse
+from pathlib import Path
+import sys
+
+# Also works directly from the checkout when pandas/matplotlib are installed.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import fastnascar
+
+RACES = {"fall": 5626, "spring": 5604}
+
+
+def main():
+    """Parse CLI options, load Hocevar's race laps, and write PNG/SVG/CSV files.
+
+    Returns:
+        None
+
+    Raises:
+        SystemExit: Invalid CLI options, missing plotting dependencies, unavailable
+            race data, or no usable Hocevar lap times.
+        OSError: Output files cannot be created.
+    """
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--race", choices=RACES, default="fall")
+    parser.add_argument("--output-dir", type=Path, default=Path(__file__).resolve().parents[1] / "outputs")
+    parser.add_argument("--show", action="store_true", help="Open the chart in a matplotlib window")
+    parser.add_argument("--refresh", action="store_true", help="Fetch fresh lap and result data")
+    args = parser.parse_args()
+
+    try:
+        import matplotlib
+        if not args.show:
+            matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        from matplotlib.ticker import MultipleLocator
+    except ImportError:
+        parser.exit(1, 'Plotting requires matplotlib. Run: python -m pip install -e ".[plot]"\n')
+
+    output_dir = args.output_dir.expanduser().resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    fastnascar.Cache.enable_cache(Path(__file__).resolve().parents[1] / ".fastnascar-cache")
+    try:
+        session = fastnascar.get_session(2026, race_id=RACES[args.race]).load(refresh=args.refresh)
+    except fastnascar.FastNASCARException as exc:
+        parser.exit(1, f"Could not load the Bristol race: {exc}\n")
+
+    # Results use a plain full name; lap feeds may add a '(C)' playoff suffix.
+    driver = session.get_driver("Carson Hocevar")
+    laps = session.laps.loc[session.laps.DriverId == driver.DriverId].sort_values("LapNumber").copy()
+    seconds = laps.LapTime.dt.total_seconds()
+    if laps.empty or seconds.notna().sum() == 0:
+        parser.exit(1, "No lap times were available for Carson Hocevar.\n")
+
+    # Reindex missing lap numbers so the line breaks across any absent records.
+    plot_seconds = seconds.set_axis(laps.LapNumber.astype(int)).reindex(range(1, int(laps.LapNumber.max()) + 1))
+    median = plot_seconds.rolling(10, min_periods=10).median()
+    fastest = laps.pick_fastest()
+    base = f"hocevar_bristol_2026_{args.race}"
+    csv_path = output_dir / f"{base}.csv"
+    png_path = output_dir / f"{base}.png"
+    svg_path = output_dir / f"{base}.svg"
+    export = laps.copy()
+    export["LapTimeSeconds"] = seconds
+    export["Rolling10LapMedianSeconds"] = laps.LapNumber.map(median)
+    export.to_csv(csv_path, index=False)
+
+    with plt.rc_context({"font.family": "DejaVu Sans", "font.size": 10,
+                         "axes.spines.top": False, "axes.spines.right": False}):
+        fig, axes = plt.subplots(2, 1, figsize=(13, 8), sharex=True,
+                                 gridspec_kw={"height_ratios": [1, 1.4]}, layout="constrained")
+        fig.patch.set_facecolor("#f7f9fc")
+        date = session.event.EventDate.strftime("%B %d, %Y")
+        fig.suptitle(f"Carson Hocevar · #{driver.DriverNumber} · Bristol 2026\n"
+                     f"{session.event.EventName} · {date}", fontsize=17, fontweight="bold")
+        for ax in axes:
+            ax.set_facecolor("white")
+            ax.plot(plot_seconds.index, plot_seconds, color="#2374ab", linewidth=0.8,
+                    marker=".", markersize=2.4, alpha=0.85, label="Recorded lap time")
+            ax.set_ylabel("Lap time (seconds)")
+            ax.grid(axis="y", color="#dce3ea", linewidth=0.6)
+            ax.set_xlim(1, max(2, int(laps.LapNumber.max())))
+            ax.xaxis.set_major_locator(MultipleLocator(50))
+        axes[0].set_title("All laps · full time range, including slow laps", loc="left", fontsize=11)
+        axes[0].legend(loc="upper right", frameon=False)
+        axes[1].plot(median.index, median, color="#e07826", linewidth=1.8,
+                     label="10-lap rolling median (all recorded laps)")
+        # Same data in both panels; only the lower panel's displayed y-range is limited.
+        lower = max(0, float(seconds.min()) - 0.5)
+        upper = max(lower + 3, float(seconds.quantile(0.75)) + 2)
+        axes[1].set_ylim(lower, upper)
+        axes[1].set_title(f"Pace detail · y-axis zoom {lower:.1f}–{upper:.1f} s; slower laps remain above",
+                          loc="left", fontsize=11)
+        axes[1].scatter([int(fastest.LapNumber)], [fastest.LapTime.total_seconds()],
+                        color="#b93645", s=38, zorder=5,
+                        label=f"Fastest: {fastest.LapTime.total_seconds():.3f} s (lap {fastest.LapNumber})")
+        axes[1].legend(loc="upper right", frameon=False, fontsize=9)
+        axes[1].set_xlabel("Hocevar's completed car lap")
+        fig.supxlabel("Source: NASCAR lap-times feed · No laps filtered · Gaps indicate missing data", fontsize=9)
+        fig.savefig(png_path, dpi=180, facecolor=fig.get_facecolor())
+        fig.savefig(svg_path, facecolor=fig.get_facecolor())
+        if args.show:
+            plt.show()
+        plt.close(fig)
+
+    print(f"{session.event.EventName} (race ID {session.event.RaceId})")
+    print(f"#{driver.DriverNumber} {driver.FullName}: {len(laps)} laps; finish P{driver.Position}")
+    print(f"Fastest lap: {fastest.LapTime.total_seconds():.3f}s on lap {fastest.LapNumber}")
+    for path in (png_path, svg_path, csv_path):
+        print(path)
+
+
+if __name__ == "__main__":
+    main()

fastnascar-0.1.0/examples/live_timing.py

@@ -0,0 +1,6 @@
+"""Show ten updates from the currently active NASCAR Cup feed."""
+import fastnascar
+
+for snapshot in fastnascar.iter_live(interval=2, max_updates=10):
+    print(f"Race {snapshot.race_id}, lap {snapshot.lap_number}, flag {snapshot.flag_state}")
+    print(snapshot.timing[["Position", "DriverNumber", "Driver", "LastLapTime"]].head())

fastnascar-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastnascar"
+version = "0.1.0"
+description = "Pandas-based NASCAR sessions, laps, results, and live timing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["nascar", "motorsport", "timing", "pandas"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["pandas>=2.2,<4"]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.8"]
+dev = ["pytest>=8", "build>=1", "twine>=6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

fastnascar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastnascar-0.1.0/src/fastnascar/__init__.py

@@ -0,0 +1,13 @@
+"""FastNASCAR: NASCAR Cup data for pandas analysis."""
+from .api import NASCARClient
+from .cache import Cache
+from .core import Laps, Session, get_event, get_event_schedule, get_session
+from .exceptions import (AmbiguousEventError, DataNotAvailableError, EventNotFoundError,
+                         FastNASCARException, InvalidDataError, SessionNotLoadedError)
+from .live import LiveSnapshot, get_live_session, iter_live, record_live, replay_live
+
+__version__ = "0.1.0"
+__all__ = ["Cache", "NASCARClient", "Laps", "Session", "get_event", "get_event_schedule",
+           "get_session", "LiveSnapshot", "get_live_session", "iter_live", "record_live", "replay_live",
+           "FastNASCARException", "DataNotAvailableError", "InvalidDataError", "SessionNotLoadedError",
+           "EventNotFoundError", "AmbiguousEventError"]

fastnascar-0.1.0/src/fastnascar/_time.py

@@ -0,0 +1,18 @@
+"""Conversions shared by historical and live timing parsers."""
+import pandas as pd
+
+
+def seconds_to_timedelta(values):
+    """Convert a Series of seconds to nanosecond-resolution pandas timedeltas.
+
+    Args:
+        values (pandas.Series): Numeric seconds or strings that represent seconds.
+
+    Returns:
+        pandas.Series: Timedeltas with the original index. Missing, nonnumeric,
+        and infinite values become ``NaT``. Empty Series keep the same dtype.
+    """
+    numeric = pd.to_numeric(values, errors="coerce")
+    numeric = numeric.mask(numeric.isin([float("inf"), -float("inf")]))
+    converted = pd.to_timedelta(numeric.fillna(0), unit="s").astype("timedelta64[ns]")
+    return converted.mask(numeric.isna())