How ibpme/fuzzy-df works
Project Type & Purpose
• fuzzy-df is a Python package designed to offer utilities for fuzzy matching and merging operations on pandas DataFrames and Series. It leverages the rapidfuzz library for similarity scoring and integrates into pandas workflows.
File Structure
• The top-level directories provide important context:
• The “src” directory contains the package code. Within it, the fuzzy_df directory holds the primary modules: match.py and merge.py.
• The “tests” directory includes our test cases for these modules.
• The “.github/workflows” directory shows that CI/CD workflows are configured (ci.yml, release.yml, staging.yaml), which means automated tests, builds, and deployments are part of the design.
• Files like pyproject.toml, uv.lock, LICENSE, and .python-version indicate a managed build/dependency system and standard packaging practices.
Components
a. Core Library:
• Fuzzy Matching Component (from src/fuzzy_df/match.py): Represents the fuzzy matching functions that compare pandas Series with a score computed via rapidfuzz.
• Fuzzy Merging Component (from src/fuzzy_df/merge.py): Represents logic to merge two pandas DataFrames or Series using fuzzy matching.
b. Dependencies:
• pandas: Essential for handling DataFrame/Series operations.
• rapidfuzz: Used for similarity computations.
• uv: The build tool showcased in the README which is used for packaging and testing.
c. Testing & CI/CD Pipeline:
• Unit Testing (tests directory): Demonstrates that the fuzzy matching and merging functionalities are verified via pytest.
• CI/CD Workflows: The .github/workflows configuration files (ci.yml, release.yml, staging.yaml) indicate automation for continuous integration, building, and release management.
d. Build & Distribution:
• Build Process: Illustrate the use of uv build command that compiles and packages the project along with the creation of distribution artifacts under the dist/ directory.
• Local install and testing commands, such as uv pip install -e ., should be noted.
Relationships and Interactions
• The building and testing pipelines should be connected, showcasing that after code is modified in the src directory, tests (in tests/) are executed automatically via the CI workflows.
Architectural Patterns & Design Principles
• Modular Design: The clear separation of matching vs. merging code ensures maintainability.
• Pipeline Integration: The integration of CI/CD (via GitHub workflows) with build/test automation emphasizes a continuous delivery model.
• Extensibility: The code supports configuration (score_cutoff, custom column names), meaning the design is flexible and can be extended.