Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
156 lines (110 loc) · 4.44 KB

CONTRIBUTING.md

File metadata and controls

156 lines (110 loc) · 4.44 KB
Raw

Contributing to nsefetch

First off, thank you for considering a contribution! nsefetch is a community project and every bug report, feature idea, and pull request makes it better.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold this standard. Please report unacceptable behavior to the maintainer via GitHub issues.

Getting Started

Prerequisites

  • Python 3.12 or 3.13
  • uv or pip

Set Up the Development Environment

# Clone the repo
git clone https://github.com/harsh-kumar-rai/nsefetch.git
cd nsefetch

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest tests/ -v --tb=short

Note: Tests that hit live NSE endpoints are gated behind the NSEFETCH_LIVE_PROBE_ENABLED=1 environment variable and will be skipped in normal test runs. Do not add live-network tests to the standard suite.

Code Style

This project uses ruff for linting and formatting.

# Check for lint issues
ruff check src/ tests/

# Auto-fix safe issues
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/

# Check formatting without modifying files
ruff format --check src/ tests/

All PRs must pass ruff check and ruff format --check before merging.

Submitting a Pull Request

  1. Fork the repository and create your branch from main:

    git checkout -b feature/your-feature-name

  2. Write tests for any new functionality. The test suite uses pytest and pytest-asyncio.

  3. Ensure all checks pass locally:

    ruff check src/ tests/
ruff format --check src/ tests/
pytest tests/ -v --tb=short

  4. Write a clear PR description explaining:

    • What the change does
    • Why it's needed
    • Any trade-offs or limitations

  5. Keep PRs focused — one logical change per PR makes review faster.

Reporting Bugs

Use the Bug Report issue template. Please include:

  • Python version and OS
  • nsefetch version (pip show nsefetch)
  • Minimal reproducible example
  • Expected vs actual behavior
  • Full traceback if applicable

Requesting Features

Use the Feature Request issue template. Good candidates include:

  • New NSE endpoints (pre-open, corporate actions, IPO data)
  • BSE support
  • Historical data integration
  • pandas / polars output helpers
  • New index names
  • Export utilities (CSV, Excel)

Check existing issues first to avoid duplicates — and feel free to comment "+1" on open requests you care about.

Project Structure

nsefetch/
├── src/nsefetch/
│   ├── __init__.py          # Public API surface
│   ├── client.py            # HTTP client with cookie bootstrap
│   ├── transport.py         # Swappable transport boundary
│   ├── fetcher.py           # NSE endpoint fetching
│   ├── normalizer.py        # Raw payload → typed schema
│   ├── schemas.py           # Pydantic data models
│   ├── circuit_breaker.py   # Failure isolation
│   ├── rate_limiter.py      # GCRA rate limiter
│   ├── cache.py             # In-memory / Redis cache
│   ├── config.py            # Settings via pydantic-settings
│   ├── exceptions.py        # Exception hierarchy
│   ├── live_probe.py        # Live connectivity probe
│   ├── providers/           # Provider base classes
│   └── services/            # MarketService / AsyncMarketService
├── tests/                   # pytest test suite
├── docs/                    # User-facing documentation
└── examples/                # Runnable usage examples (Wave 2)

Thank you for contributing! 🎉