Development Guide

This guide is intended for developers who want to contribute to pyjiit or understand its internal implementation. It covers the development environment setup, project structure, build system, and development workflows.

For information about using pyjiit as a library, see Getting Started. For details about the documentation system, see Documentation System. For CI/CD workflows, see Deployment and CI/CD.

Prerequisites and Requirements

pyjiit development requires the following tools and environment:

The project uses Poetry as its primary build and dependency management tool. All dependencies are declared in pyproject.toml9-11 for runtime and pyproject.toml19-21 for documentation builds.

Sources: pyproject.toml1-28

Development Environment Setup

Installing Poetry

Poetry must be installed before setting up the development environment:

pip install poetry

Cloning and Setting Up the Repository

# Clone the repository
git clone https://github.com/codelif/pyjiit
cd pyjiit

# Install all dependencies including documentation tools
poetry install --with docs

# Activate the virtual environment
poetry shell

The poetry install command reads pyproject.toml1-28 and poetry.lock1-1054 to create a reproducible development environment with exact dependency versions locked.

Verifying the Installation

# Check Python environment
poetry run python --version

# Import the library
poetry run python -c "from pyjiit import Webportal; print('Success')"

Sources: pyproject.toml1-28 poetry.lock1-1054

Development Environment Architecture

The following diagram shows how different components of the development environment interact:

Sources: pyproject.toml1-28 poetry.lock1-1054 .gitignore1-166

Project File Structure Overview

For detailed information about each directory and file, see Project Structure.

Sources: pyproject.toml1-28 .gitignore1-166 LICENSE1-22

Key Development Files and Their Purposes

Sources: pyproject.toml1-28 poetry.lock1-1054 pyjiit/exceptions.py1-19 .gitignore1-166

Understanding the Exception Hierarchy

The pyjiit library defines a custom exception hierarchy for fine-grained error handling:

Exception Usage Patterns:

• APIError - Raised by general API methods when server returns error responses
• LoginError - Raised by student_login() when credentials are invalid
• SessionExpired - Raised when HTTP 401 detected or token validity expires
• NotLoggedIn - Raised by @authenticated decorator when methods called before login
• AccountAPIError - Raised by account management methods like set_password()

Sources: pyjiit/exceptions.py1-19

Dependency Management with Poetry

Understanding pyproject.toml

The pyproject.toml1-28 file serves multiple purposes:

1. Project Metadata (pyproject.toml1-17):

   • Package name, version, description
   • Author information
   • License and README
   • Python version requirement (>=3.9)
   • Project URLs

2. Runtime Dependencies (pyproject.toml9-12):

   • requests - HTTP client for API calls
   • pycryptodome - AES encryption implementation

3. Documentation Dependencies (pyproject.toml19-21):

   • sphinx - Documentation generator
   • furo - Modern documentation theme
   • Separated into docs group for optional installation

4. Build System (pyproject.toml23-25):

   • Uses poetry-core as the build backend
   • Complies with PEP 517/518 standards

Understanding poetry.lock

The poetry.lock1-1054 file contains:

• Exact versions of all dependencies and their transitive dependencies
• File hashes for verification (poetry.lock10-13)
• Platform markers for conditional dependencies (poetry.lock172)
• Dependency groups separating main and docs dependencies

This ensures reproducible builds across different environments and time periods.

For detailed dependency management workflows, see Build System and Dependencies.

Sources: pyproject.toml1-28 poetry.lock1-1054

Common Development Tasks

Adding a New Dependency

# Add runtime dependency
poetry add package-name

# Add development/documentation dependency
poetry add --group docs package-name

# Update poetry.lock after manual pyproject.toml edits
poetry lock

Running Code Locally

# Activate Poetry shell
poetry shell

# Run Python scripts
python your_script.py

# Or run without activating shell
poetry run python your_script.py

Building the Package

# Build distribution packages (wheel and sdist)
poetry build

# Output will be in dist/ directory
# - pyjiit-0.1.0a8-py3-none-any.whl
# - pyjiit-0.1.0a8.tar.gz

Version Management

The version is defined in pyproject.toml3:

version = "0.1.0a8"

To bump the version:

# Update version in pyproject.toml
poetry version patch   # 0.1.0a8 -> 0.1.0a9
poetry version minor   # 0.1.0 -> 0.2.0
poetry version major   # 0.1.0 -> 1.0.0

Sources: pyproject.toml1-28

Development Workflow Lifecycle

For detailed testing workflows, see Testing and Development Workflow. For CI/CD details, see GitHub Actions Workflows.

Sources: pyproject.toml1-28 .gitignore1-166

Code Quality Standards

File Exclusions

The .gitignore1-166 file excludes:

• Build artifacts: dist/, build/, *.egg-info/ (.gitignore9-27)
• Python cache: __pycache__/, *.pyc (.gitignore1-4)
• Virtual environments: .venv/, venv/ (.gitignore124-131)
• Documentation builds: docs/_build/ (.gitignore71-72)
• IDE files: .idea/ (.gitignore162)
• Test files: test.py (.gitignore165)

Module Organization Principles

1. Separation of Concerns:

   • wrapper.py - API orchestration
   • encryption.py - Security operations
   • utils.py - Generic utilities
   • Data models in separate files

2. Exception Hierarchy:

   • Specific exceptions for different error categories (pyjiit/exceptions.py1-19)
   • Allows precise error handling in client code

3. Minimal Public API:

   • Only Webportal class exported from pyjiit/__init__.py
   • Internal modules remain private

Sources: .gitignore1-166 pyjiit/exceptions.py1-19

Next Steps

• Project Structure - Detailed directory layout and module organization
• Build System and Dependencies - Deep dive into Poetry usage and dependency management
• Testing and Development Workflow - How to test, debug, and contribute new features

For setting up documentation builds locally, see Building Documentation. For understanding how releases are published, see Publishing to PyPI.

Sources: pyproject.toml1-28 poetry.lock1-1054 pyjiit/exceptions.py1-19 .gitignore1-166