Merge remote-tracking branch 'upstream/master'

Author: nmodi

.circleci/config.yml

@@ -5,7 +5,6 @@ orbs:
 
 references:
   python_images: &python_images
-    - "cimg/python:3.9"
     - "cimg/python:3.10"
     - "cimg/python:3.11"
     - "cimg/python:3.12"
@@ -35,10 +34,13 @@ jobs:
             - snyk/scan
       - run:
           name: run tests
-          command: poetry run pytest
-      - run: 
-          name: run flake8
-          command: poetry run flake8
+          command: poetry run pytest tests/unit
+      - run:
+          name: run tests
+          command: poetry run pytest tests/integration -m "vcr"
+      - run:
+          name: run ruff
+          command: poetry run ruff check && poetry run ruff format --check
 
   release:
     docker:

.devcontainer/Dockerfile

@@ -0,0 +1,45 @@
+# Specify the Python version and base OS for the container
+# VARIANT allows customization of Python version (default: 3.10 on Debian Bullseye)
+ARG VARIANT="3.10-bullseye"
+
+# Use Microsoft's official Python dev container as the base image
+FROM mcr.microsoft.com/devcontainers/python:1-${VARIANT}
+
+# Install system packages as root user before switching to vscode
+# - ODBC drivers for SQL Server connectivity
+# - GitHub CLI for PR management and git workflows
+RUN apt-get update && apt-get install -y \
+    unixodbc \
+    unixodbc-dev \
+    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /usr/share/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y gh \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Switch from root to the vscode user for security and proper file permissions
+# The vscode user is pre-configured in the base image with development tools
+USER vscode
+
+# Download and install Poetry package manager for the vscode user
+# Poetry manages Python dependencies and virtual environments
+RUN curl -sSL https://install.python-poetry.org -o /tmp/install-poetry.py \
+    && python3 /tmp/install-poetry.py \
+    && rm /tmp/install-poetry.py
+
+# Add Poetry's installation directory to the system PATH
+# This allows the 'poetry' command to be run from anywhere
+ENV PATH="/home/vscode/.local/bin:$PATH"
+
+# Configure Poetry to create virtual environments inside the project directory
+# This creates a .venv folder in your project root instead of Poetry's global cache
+# This setting acts as a "gate" - it ensures proper environment setup before shells can run
+# Set cache directory to /tmp to enable fast package downloads during build
+# while preventing cache bloat in the final Docker image
+RUN poetry config virtualenvs.in-project true \
+    && poetry config cache-dir /tmp/poetry_cache
+
+# Set the working directory where your project files will be mounted
+# This is where VS Code will open and where your code will live
+WORKDIR /workspace

.devcontainer/devcontainer.json

@@ -1,29 +1,72 @@
 {
-	"containerEnv": {
-		"PYTHON_VERSION": "3.11"
-	},
-	"features": {
-		"ghcr.io/devcontainers/features/python:latest": {},
-		"ghcr.io/devcontainers-contrib/features/poetry:2": {}
-	},
-	"image": "mcr.microsoft.com/devcontainers/base:debian-11",
-	"name": "nba_api",
-	"postCreateCommand": "bash .devcontainer/postCreateCommand.sh",
-	"remoteEnv": {
-		"PYTHONUTF8": "1"
-	},
+    // Display name for this dev container configuration
+    "name": "NBA API",
+    
+    // Build configuration for the container
+    "build": {
+        // Path to the Dockerfile relative to the build context
+        "dockerfile": "Dockerfile",
+        // Build context directory - ".." means parent directory of .devcontainer folder
+        // This allows Docker to access project files outside the .devcontainer directory
+        "context": ".."
+    },
+
+	// VS Code specific customizations
 	"customizations": {
 		"vscode": {
+
+			// Extensions to install automatically in the container
+            // These provide Python development tools, linting, and formatting
 			"extensions": [
-				"ms-python.black-formatter",
-				"ms-python.flake8",
-				"ms-python.python",
-				"ms-python.vscode-pylance",
-				"ms-toolsai.jupyter",
-				"ms-toolsai.jupyter-keymap",
-				"ms-toolsai.jupyter-renderers",
-				"ms-toolsai.vscode-jupyter-powertoys"
-			]
-		}
-	}
+                "ms-python.black-formatter",
+                "ms-python.flake8",
+                "ms-python.isort",
+                "ms-python.pylint",
+                "ms-python.python",
+                "ms-python.vscode-pylance",
+                "ms-toolsai.jupyter",
+                "ms-toolsai.jupyter-keymap",
+                "ms-toolsai.jupyter-renderers",
+                "ms-toolsai.vscode-jupyter-powertoys",
+                "tamasfe.even-better-toml"
+            ],
+
+            // VS Code settings to apply in the container
+            "settings": {
+                
+                // Enable Python linting globally across all Python files
+                // This provides real-time error detection and code quality feedback
+                "python.linting.enabled": true,
+                
+                // Enable pylint as the primary linting tool
+                // Pylint provides comprehensive code analysis and style checking
+                "python.linting.pylintEnabled": true,
+                
+                // Automatically format Python files when saving
+                // This ensures consistent code style across the project
+                "editor.formatOnSave": true,
+                
+                // Use Black as the Python code formatter
+                // Black is an opinionated formatter that enforces consistent style
+                "python.formatting.provider": "black",
+                
+                // Set bash as the default terminal shell in Linux containers
+                // This ensures consistent shell behavior across different environments
+                "terminal.integrated.defaultProfile.linux": "bash"
+            }
+        }
+    },
+
+    // Ports to forward from container to host (empty array = no ports forwarded)
+    // Add port numbers here if your application serves web content (e.g., [8000, 3000])
+    "forwardPorts": [],
+    
+    // User to connect as when attaching to the container
+    // "vscode" user has proper permissions and development tools pre-configured
+    "remoteUser": "vscode",
+
+    // Command to run after the container is created and VS Code connects
+    // This executes the post-create script that sets up Poetry and dependencies
+    // Runs only once when the container is first created, not on every restart
+    "postCreateCommand": "bash .devcontainer/post-create-command.sh"
 }

.devcontainer/post-create-command.sh

@@ -0,0 +1,29 @@
+pip install --upgrade pip
+poetry install
+# Activate poetry environment
+source $(poetry env info --path)/bin/activate
+
+# Update PYTHONPATH to include the virtual environment's Python interpreter
+echo "export PYTHON_PATH=$(poetry env info --path)/bin/python" >> ~/.bashrc
+#!/bin/bash
+# Shebang: tells the system to execute this script using bash
+
+# Exit immediately if any command fails (prevents partial setup)
+# This ensures the development environment is either fully set up or fails clearly
+set -e
+
+# Display status message to user during container setup
+echo "Setting up development environment..."
+
+# Install all dependencies from pyproject.toml and poetry.lock
+# --with linting,test includes optional dependency groups for development tools
+# This creates the .venv directory and installs packages inside it
+poetry install
+
+# Configure shell activation for all future terminal sessions
+# This adds a command to .bashrc that automatically activates the Poetry environment
+# The '2>/dev/null || true' suppresses errors if Poetry environment doesn't exist yet
+echo 'eval "$(poetry env activate)" 2>/dev/null || true' >> ~/.bashrc
+
+# Display completion message to user
+echo "Setup complete! Poetry environment activated."

.devcontainer/postCreateCommand.sh

@@ -0,0 +1,8 @@
+# CODEOWNERS file for nba_api
+# This file defines who will be automatically requested for review
+# when someone opens a pull request.
+#
+# More information: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owners for everything in the repository
+* @swar

.flake8

@@ -131,4 +131,7 @@ nba_api/library/debug/
 .history/
 
 # Built Visual Studio Code Extensions
-*.vsix
+*.vsix
+
+# Git worktrees
+.worktrees/

.github/CODEOWNERS

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff          # lint + auto-fix
+        args: [--fix]
+      - id: ruff-format   # format

.gitignore

@@ -1,13 +1,12 @@
 {
     "editor.formatOnSave": true,
-    "flake8.args": [
-        "--config=.flake8"
-    ],
-    "python.formatting.provider": "black",
-    "python.formatting.blackArgs": [
-        "--line-length",
-        "88"
-    ],
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit"
+        }
+    },
     "python.analysis.diagnosticSeverityOverrides": {
         "reportUnboundVariable": "information",
         "reportImplicitStringConcatenation": "warning",
@@ -18,4 +17,4 @@
     ],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true
-}
+}