DEV Community: Abhinav

Shipping 1.0.0: From Local Repo to a Published Python Package

Abhinav — Mon, 24 Nov 2025 23:48:16 +0000

Overview

This post documents releasing version 1.0.0 of the project to Python’s ecosystem. It covers: tooling choice, release steps, lessons learned, user testing feedback, required code changes, and installation/usage instructions.

Tooling & Registry Choices

Build backend: setuptools (standard pyproject.toml)
Build helper: build
Upload tool: twine
Staging registry: TestPyPI (https://test.pypi.org)
Production registry: PyPI (https://pypi.org)

Release Workflow (Detailed)

Clean repo

   git status

Update version in pyproject.toml (set to 1.0.0).
Run tests

   python -m pytest

(Optional) Add or confirm __all__ exports and __init__.py.
Build distributions

   python -m pip install --upgrade build twine
   python -m build
   ls dist/

Validate artifacts

   python -m twine check dist/*

Tag release

   git tag -a v1.0.0 -m "Release 1.0.0"
   git push origin v1.0.0

Upload to TestPyPI

   python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Fresh environment install test

   python -m venv .venv-test
   source .venv-test/bin/activate
   python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple your-package-name
   python -c "import your_package; print(your_package.__version__)"

Upload to PyPI
```
python -m twine upload dist/*
```
Update README: add install, usage, changelog section.
Optional: create a GitHub Release referencing tag.

Minimal `pyproject.toml` Example

[project]
name = "your-package-name"
version = "1.0.0"
description = "Concise description of the package."
readme = "README.md"
requires-python = ">=3.9"
license = { text = "MIT" }
authors = [
  { name = "Your Name", email = "you@example.com" }
]
keywords = ["context", "repository", "utility"]
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
  "Development Status :: 5 - Production/Stable"
]

[project.optional-dependencies]
dev = ["pytest", "build", "twine"]

[tool.setuptools]
packages = ["your_package"]

Code Adjustments

Added project metadata in pyproject.toml.
Ensured package has your_package/__init__.py.
Exposed __version__ inside package to avoid duplication.
Expanded README for install and usage. No functional logic changes required.

Example __init__.py:

__version__ = "1.0.0"

from .core import main_tool  # example public API

User Testing Session Notes

Observed issues:

Missing virtual environment usage (user attempted global install).
Initial confusion about required Python version.
User looked for quick start; added a “5‑line usage” block. Resolutions:
Added explicit venv commands.
Added Python version badge.
Clarified import path with a minimal working snippet.

Installation (Users)

Production (PyPI):

python -m pip install your-package-name

TestPyPI (staging validation):

python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple your-package-name

Upgrade:

python -m pip install -U your-package-name

Uninstall:

python -m pip uninstall your-package-name

Quick Start

from your_package import main_tool

result = main_tool("input text")
print(result)

CLI example (if provided):

your-package-name --help
your-package-name run --input data.txt

Release Checklist (Reusable)

[ ] Bump version
[ ] Run tests
[ ] Build sdist + wheel
[ ] twine check
[ ] Tag and push
[ ] TestPyPI upload
[ ] Fresh env install test
[ ] PyPI upload
[ ] Update README/changelog
[ ] Announce

Useful Links

PyPI: https://pypi.org
TestPyPI: https://test.pypi.org
build: https://pypi.org/project/build/
twine: https://pypi.org/project/twine/
Packaging User Guide: https://packaging.python.org/

Building Robust CI/CD Pipeline

Abhinav — Sat, 15 Nov 2025 03:55:57 +0000

In this post, I'll share my experience implementing a comprehensive CI/CD pipeline using GitHub Actions, writing tests for an existing codebase, and the valuable lessons learned along the way.

Setting Up GitHub Actions: From Zero to Production-Ready

The Challenge:

When I first approached this project, I was working with repo-contextr, a Python CLI tool that analyzes git repositories and packages their content for sharing with Large Language Models (LLMs). The project already had a solid foundation but lacked automated testing and continuous integration.

Designing the CI Workflow

In this, I made sure that I opt a robust approach to maintain the following:

Multi-platform compatibility (Linux, Windows, macOS)
Code quality through linting and formatting
Type safety with static analysis
Comprehensive test coverage
Successful package building

Here's the GitHub Actions workflow I implemented:

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ['3.12']

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
        cache: 'pip'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install "ruff>=0.8.0" "mypy>=1.17.1" "pytest>=8.4.2" "pytest-cov>=6.0.0"
        pip install --editable .

    - name: Verify installation
      run: |
        python -c "import contextr; print('Package imported successfully')"
        python -c "from contextr.cli import app; print('CLI imported successfully')"

    - name: Run ruff linting
      run: |
        ruff check src tests

    - name: Run ruff formatting check
      run: |
        ruff format --check src tests

    - name: Run mypy type checking
      run: |
        mypy src
      continue-on-error: true

    - name: Run tests with coverage
      run: |
        pytest --cov=src --cov-report=xml --cov-report=term

  build:
    runs-on: ubuntu-latest
    needs: test

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'

    - name: Install build dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build

    - name: Build package
      run: python -m build

    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: dist-packages
        path: dist/

Writing Tests for Someone Else's Code: A Different Perspective

Understanding the perspective:

The Repo-Contextor already had a modular architecture as displayed below:

src/contextr/
├── commands/          # CLI command implementations
├── config/           # Configuration management
├── discovery/        # File discovery logic
├── git/             # Git operations
├── processing/      # File reading and processing
└── statistics/      # Token counting and stats

My Approach:

File Discovery Module: The file discovery system needed comprehensive testing for various scenarios:

def test_discover_files_with_pattern(self, temp_dir):
    """Test discovering files with include pattern."""
    (temp_dir / "file1.py").write_text("# python")
    (temp_dir / "file2.js").write_text("// javascript")
    (temp_dir / "file3.py").write_text("# python")

    result = discover_files([temp_dir], include_pattern="*.py")
    assert len(result) == 2
    assert all(f.suffix == ".py" for f in result)

Git Operations: Git integration required careful mocking to test various scenarios:

def test_get_git_info_valid_repo(self, sample_git_repo):
    """Test getting git info from valid repository."""
    result = get_git_info(sample_git_repo)

    assert result is not None
    assert isinstance(result, dict)
    assert "commit" in result
    assert "branch" in result
    assert "author" in result
    assert "date" in result

CLI Interface: Testing the CLI required understanding the Typer framework and proper mocking:

def test_basic_execution(self, mock_config, mock_package):
    """Test basic CLI execution without errors."""
    # Mock configuration
    mock_config_obj = Mock()
    mock_config_obj.paths = ["."]
    mock_config_obj.include = None
    mock_config_obj.recent = False
    mock_config_obj.output = None

Outcome:

Test count: Increased from 108 to 160 tests (+48% increase)
Code coverage: Improved from 35.72% to 78.03% (+42.31% improvement)
Module coverage: Several modules went from 0% to 95%+ coverage.

Conclusion:

Implementing CI/CD isn't just about automation—it's about adopting a mindset of continuous improvement and quality assurance. The process taught me several valuable lessons: Quality Gates Matter, Fast Feedback Loops, Documentation Through Code, Confidence in Changes.

Refactoring: A way to write better Code

Abhinav — Sat, 11 Oct 2025 02:00:22 +0000

As I have landed in the Week 6, I got introduced to the new practice and that is Refactoring, which literally means to make changes in the internal structure keep the functionality not only intact but also enhancing it to scale when it comes to some projects. I applied onto my project i.e. Repository-Contextor and enhanced its actual working so as to scale well and come up with better tweeks

I start with focusing on the function extraction- by pulling out th reusable logic for the verbose logging, rendering and processing. Then I collected and joined the shared utilities- like language mapping and data building. I then created a single source to get the constants such as file extensions and skip directories. I then encapsulated the data and its analysis into the Repository_Analyzer class to make the code following the object-Oriented pattern.

I addressed naming hygiene, replacing ambiguous variables like f and p with descriptive names like discovered_fileand resolved_path, making the code self-documenting. Improvement made were incremental.

Using Git: Rebasing, Squashing

Working on the refactoring branch was not a new challenge for me but when I interactively rebase my branch with the main using git rebase -i main, I squashed all the small incremental changes into one commit without cluttering the log.Merging back to main via fast-forward ensured a clean integration, and pushing to GitHub made the work visible. I faced issues while I was making changes. Inconsistent language mappings, issues arose during file reading consolidation, and subtle path-handling errors arose during extraction part. Talking about the issues- Yesss, alot of them. Import errors during code splitting and parameter mismatches in class refactoring caused brief disruptions. Ultimately, refactoring invests in code quality. Follow iterative patterns—extract, consolidate, encapsulate, refine—to transform technical debt into scalable excellence.

From 0 to 0.1

Abhinav — Sat, 20 Sep 2025 03:48:55 +0000

When developers ask for help from ChatGPT or other LLMs, they usually struggle to share their code effectively. Copy-pasting individual files loses important context: the project structure, related files, and the big picture.

Repo-Contextor solves this problem by scanning a local Git repository and producing a well-structured text file with the repository’s contents. This file can then be shared with an LLM for debugging, explanation, or collaboration.

Technical Details

Repo-Contextor is written in Python, structured as a CLI tool. The repo is organized under src/rcpack/ with separate modules for:

cli.py – command-line interface using click.
discover.py – logic to walk the file system and collect files.
gitinfo.py – gathers repository metadata.
treeview.py – builds the project tree structure.
renderers/ – handles output formats (Markdown, JSON/YAML).
This modular design makes it easier to add features in future releases.

Working on Release 0.1 taught me a lot about:

1.Project structure:

How to lay out a Python CLI tool using pyproject.toml and src/ layout.
Why separating concerns into modules makes code more maintainable.

2.Git and GitHub workflows

How to set up a new repository properly (with README, LICENSE, etc.).
How to manage issues, commits, and releases in GitHub.

Packaging for LLMs

The challenges of providing enough context without overwhelming the model.
Why tree views and filtered file outputs are more useful than raw dumps.

In challenges, I faced merging issues, lots of conflict as well as some basic issues such as .vscode/ and rcpack.egg_info/ got checked in and had to re-read some basics of removing it while dealing with multiple folders.

Commitment

Abhinav — Sat, 20 Sep 2025 03:40:34 +0000

It's been 3 weeks and the word open-source and to practice has become part of my life. I have taken a short step towards it by contributing in my peer's repository share-my-repo, where I added a feature. As everybody says every step count so this is out of the whole journey.
I tried many tools and played with many commands. Stackoverflow and other guiding websites became my favourite. I did it by skimming through the code and then filling the issue requesting to add the feature into it.

Once the issue was filed, I forked the repo, cloned it locally, and created a new branch:

git checkout -b issue-X

Then, In cli.py, I added a new --recent/-r flag using the existing click options. This was straightforward once I understood how the CLI arguments were being handled.

The main technical challenge was in file_processor.py
. I created an is_recent(file, days=7) helper function that checks the file’s last modified timestamp with Python’s os.stat().st_mtime.

The logic works by comparing the file’s modification time to the current time (via time.time()), and converting the difference into days. If the difference is less than or equal to 7, the file is considered “recent.”

Edge cases included:

Non-existent files → handled with a try/except FileNotFoundError.

Empty repositories → the function returns an empty list gracefully.

Finally, in formatter.py, I added a new section "## Recent Changes". This section outputs each recent file along with how many days ago it was modified.

`Example:

## Recent Changes
- src/main.py (modified 2 days ago)
- README.md (modified 5 days ago)`

I updated the README.md to explain the new flag, its usage, and examples.

Code Review: As a Beginner

Abhinav — Sat, 13 Sep 2025 01:57:53 +0000

When it comes to the code review, I would choose asynchronous approach other as the reviewer is free of any pressure and skim thoroughly the whole codebase keeping the technical stuff in the mind .This is helpful in understanding the design and working of the project.Reviewing Someone else’s code was bit new experience is to me as I have never did this before.
Though the code was structured well but one key aspect i.e. the output was not getting generating well. Concept of Modularity made it easy for me to jump from one part to another without me feeling lost into it.
The project had no tests whatsoever, making it impossible to verify functionality or catch regressions. And this matters because Without tests, every change becomes a potential breaking change. The developer can't be confident that modifications work correctly, and contributors can't verify their changes don't break existing functionality.
The project lacked any build system (Makefile, CMake, etc.) and had minimal documentation for setup and usage.A project without proper build instructions is essentially unusable by others. It creates a barrier to entry that prevents adoption and contribution.
To perform the review of any project one must have to have wide range of knowledge regarding that language as well as its practical implementation. Insights from this were - Without tests, fundamental issues can go unnoticed and Approaching code from a user's perspective reveals usability issues that developers might overlook.

Open-Source: lets Unleash it

Abhinav — Fri, 05 Sep 2025 22:30:57 +0000

Hi readers, this blog is going to be the foundational stone of my open-source journey as from now onwards I will be working closely to build in public which is often overlooked by most of computer science beginners. I have taken the open-source development as a course under the mentorship of David Humphrey who have dived deep in open source world.
I have been aware about this way of learning and applying on industry level codebase but didn't walk forward to it and now I believe the following 4 months will be full of grind and to prove that things are achievable with positive intent.
I am drawn towards this because of recognition and rewarding nature it come up within thin the developers community which open the gates to the brilliant minds who aims to make an impact in the society via tech.

ProtonMail - Privacy for All

I want to draw your attention towards one of the renown open source project Proton Mail. I got to about this platform in search of reliable mailing application and privacy it provides is strong. Pardon me if I don't sound technical at this stage but sooner I will figure out the underlying technolgy and my contribution to the open-source community.
I would be highly thankful for all the comments and would like to learn from the best.