dsbro 0.1.0__tar.gz

dsbro-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# local planning / AI docs
+CLAUDE.md
+dsbro_master_plan.md
+
+# python cache
+__pycache__/
+*.py[cod]
+
+# virtual envs
+.venv/
+venv/
+env/
+
+# build artifacts
+build/
+dist/
+*.egg-info/
+
+# test / lint cache
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# notebook junk
+.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

dsbro-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial project scaffold
+- Added `dsbro.utils`
+- Added `dsbro.io`
+- Added test coverage for the foundation modules
+

dsbro-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Ibrahim Qasmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

dsbro-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: dsbro
+Version: 0.1.0
+Summary: Your Data Science Bro. One import away.
+Project-URL: Homepage, https://github.com/muhammadibrahim313/dsbro
+Project-URL: Documentation, https://github.com/muhammadibrahim313/dsbro
+Project-URL: Repository, https://github.com/muhammadibrahim313/dsbro
+Project-URL: Issues, https://github.com/muhammadibrahim313/dsbro/issues
+Author: Muhammad Ibrahim Qasmi
+License: MIT
+License-File: LICENSE
+Keywords: data-science,eda,kaggle,machine-learning,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: seaborn>=0.12
+Provides-Extra: all
+Requires-Dist: catboost>=1.2; extra == 'all'
+Requires-Dist: lightgbm>=4.0; extra == 'all'
+Requires-Dist: optuna>=3.6; extra == 'all'
+Requires-Dist: plotly>=5.22; extra == 'all'
+Requires-Dist: xgboost>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: catboost>=1.2; extra == 'ml'
+Requires-Dist: lightgbm>=4.0; extra == 'ml'
+Requires-Dist: optuna>=3.6; extra == 'ml'
+Requires-Dist: xgboost>=2.0; extra == 'ml'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.22; extra == 'plotly'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/muhammadibrahim313/dsbro/main/imgs/dsbro.png" alt="dsbro logo" width="320">
+</p>
+
+# dsbro
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/muhammadibrahim313/dsbro/blob/main/LICENSE)
+[![Repo](https://img.shields.io/badge/github-dsbro-black.svg)](https://github.com/muhammadibrahim313/dsbro)
+
+Your Data Science Bro. One import away.
+
+`dsbro` is a lightweight Python toolkit for notebook-heavy data science work. It is built for the
+repeated workflow most people have in Kaggle, Colab, and local Jupyter notebooks: setup, load
+data, inspect it, clean it, visualize it, and train a baseline model fast.
+
+## What dsbro covers
+
+- `dsbro.utils`: notebook setup, seeding, timers, system info, downloads, simple parallel work
+- `dsbro.io`: file loading, saving, previews, directory trees, file search, submission helpers
+- `dsbro.eda`: overview tables, missing-value analysis, drift checks, target analysis, comparisons
+- `dsbro.prep`: encoding, scaling, missing-value filling, feature engineering, memory reduction
+- `dsbro.viz`: themed matplotlib and optional plotly charts for fast notebook visuals
+- `dsbro.metrics`: classification and regression metrics in one place
+- `dsbro.ml`: model comparison, cross-validation, training, tuning, stacking, pseudo-labeling
+- `dsbro.text`: text cleaning, tokenization, word frequencies, and TF-IDF features
+
+## Current status
+
+Implemented now:
+
+- Core package scaffold and packaging
+- `utils`, `io`, `eda`, `prep`, `viz`, `metrics`, `ml`, and `text`
+- Built-in help and about/version entry points
+- Tests across the implemented modules
+- Quickstart notebook in [examples/quickstart.ipynb](https://github.com/muhammadibrahim313/dsbro/blob/main/examples/quickstart.ipynb)
+
+Still planned:
+
+- Final polish for docs/examples
+- Additional ML/deep-learning extras over time
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install dsbro
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/muhammadibrahim313/dsbro.git
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[ml]"
+pip install -e ".[plotly]"
+pip install -e ".[all]"
+```
+
+PyPI packaging is scaffolded, but this repository is still in active buildout.
+
+## Quick example
+
+```python
+import dsbro
+import pandas as pd
+
+dsbro.setup()
+
+train = pd.DataFrame(
+    {
+        "age": [22, 35, 41, 28],
+        "city": ["lahore", "karachi", "lahore", "islamabad"],
+        "purchased": [0, 1, 1, 0],
+    }
+)
+
+overview = dsbro.eda.overview(train)
+processed, report = dsbro.prep.auto_preprocess(train, target="purchased")
+leaderboard = dsbro.ml.compare(train, target="purchased", cv=2)
+```
+
+## Help system
+
+`dsbro` includes a built-in cheatsheet:
+
+```python
+dsbro.help()
+dsbro.help("viz")
+dsbro.help("encode")
+dsbro.about()
+dsbro.version()
+```
+
+## Notebook example
+
+The repository includes a walkthrough notebook:
+
+- [examples/quickstart.ipynb](https://github.com/muhammadibrahim313/dsbro/blob/main/examples/quickstart.ipynb)
+
+It demonstrates:
+
+- `dsbro.setup()`
+- `dsbro.eda.overview()`
+- `dsbro.prep.datetime_features()`
+- `dsbro.prep.text_features()`
+- `dsbro.prep.auto_preprocess()`
+- `dsbro.viz.bar()`
+- `dsbro.ml.compare()`
+
+## Development
+
+```bash
+pytest tests/ -v
+ruff check dsbro/ tests/
+ruff format dsbro/ tests/
+python -m build
+```
+
+## Roadmap
+
+- Expand example notebooks
+- Add GitHub Actions CI
+- Publish to TestPyPI, then PyPI
+- Continue polishing module docs and tutorial coverage
+
+## License
+
+MIT. See [LICENSE](https://github.com/muhammadibrahim313/dsbro/blob/main/LICENSE).

dsbro-0.1.0/README.md

@@ -0,0 +1,140 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/muhammadibrahim313/dsbro/main/imgs/dsbro.png" alt="dsbro logo" width="320">
+</p>
+
+# dsbro
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/muhammadibrahim313/dsbro/blob/main/LICENSE)
+[![Repo](https://img.shields.io/badge/github-dsbro-black.svg)](https://github.com/muhammadibrahim313/dsbro)
+
+Your Data Science Bro. One import away.
+
+`dsbro` is a lightweight Python toolkit for notebook-heavy data science work. It is built for the
+repeated workflow most people have in Kaggle, Colab, and local Jupyter notebooks: setup, load
+data, inspect it, clean it, visualize it, and train a baseline model fast.
+
+## What dsbro covers
+
+- `dsbro.utils`: notebook setup, seeding, timers, system info, downloads, simple parallel work
+- `dsbro.io`: file loading, saving, previews, directory trees, file search, submission helpers
+- `dsbro.eda`: overview tables, missing-value analysis, drift checks, target analysis, comparisons
+- `dsbro.prep`: encoding, scaling, missing-value filling, feature engineering, memory reduction
+- `dsbro.viz`: themed matplotlib and optional plotly charts for fast notebook visuals
+- `dsbro.metrics`: classification and regression metrics in one place
+- `dsbro.ml`: model comparison, cross-validation, training, tuning, stacking, pseudo-labeling
+- `dsbro.text`: text cleaning, tokenization, word frequencies, and TF-IDF features
+
+## Current status
+
+Implemented now:
+
+- Core package scaffold and packaging
+- `utils`, `io`, `eda`, `prep`, `viz`, `metrics`, `ml`, and `text`
+- Built-in help and about/version entry points
+- Tests across the implemented modules
+- Quickstart notebook in [examples/quickstart.ipynb](https://github.com/muhammadibrahim313/dsbro/blob/main/examples/quickstart.ipynb)
+
+Still planned:
+
+- Final polish for docs/examples
+- Additional ML/deep-learning extras over time
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install dsbro
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/muhammadibrahim313/dsbro.git
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[ml]"
+pip install -e ".[plotly]"
+pip install -e ".[all]"
+```
+
+PyPI packaging is scaffolded, but this repository is still in active buildout.
+
+## Quick example
+
+```python
+import dsbro
+import pandas as pd
+
+dsbro.setup()
+
+train = pd.DataFrame(
+    {
+        "age": [22, 35, 41, 28],
+        "city": ["lahore", "karachi", "lahore", "islamabad"],
+        "purchased": [0, 1, 1, 0],
+    }
+)
+
+overview = dsbro.eda.overview(train)
+processed, report = dsbro.prep.auto_preprocess(train, target="purchased")
+leaderboard = dsbro.ml.compare(train, target="purchased", cv=2)
+```
+
+## Help system
+
+`dsbro` includes a built-in cheatsheet:
+
+```python
+dsbro.help()
+dsbro.help("viz")
+dsbro.help("encode")
+dsbro.about()
+dsbro.version()
+```
+
+## Notebook example
+
+The repository includes a walkthrough notebook:
+
+- [examples/quickstart.ipynb](https://github.com/muhammadibrahim313/dsbro/blob/main/examples/quickstart.ipynb)
+
+It demonstrates:
+
+- `dsbro.setup()`
+- `dsbro.eda.overview()`
+- `dsbro.prep.datetime_features()`
+- `dsbro.prep.text_features()`
+- `dsbro.prep.auto_preprocess()`
+- `dsbro.viz.bar()`
+- `dsbro.ml.compare()`
+
+## Development
+
+```bash
+pytest tests/ -v
+ruff check dsbro/ tests/
+ruff format dsbro/ tests/
+python -m build
+```
+
+## Roadmap
+
+- Expand example notebooks
+- Add GitHub Actions CI
+- Publish to TestPyPI, then PyPI
+- Continue polishing module docs and tutorial coverage
+
+## License
+
+MIT. See [LICENSE](https://github.com/muhammadibrahim313/dsbro/blob/main/LICENSE).

dsbro-0.1.0/dsbro/__init__.py

@@ -0,0 +1,124 @@
+"""Top-level package exports for dsbro."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from dsbro import eda, io, metrics, ml, prep, text, utils, viz
+from dsbro._version import __version__
+from dsbro.utils import setup
+
+_MODULES = {
+    "io": io,
+    "eda": eda,
+    "prep": prep,
+    "viz": viz,
+    "ml": ml,
+    "metrics": metrics,
+    "utils": utils,
+    "text": text,
+}
+
+_MODULE_SUMMARIES = {
+    "io": "File and directory utilities",
+    "eda": "Exploratory data analysis helpers",
+    "prep": "Preprocessing and feature engineering",
+    "viz": "Visualization helpers with dsbro theming",
+    "ml": "Model comparison, training, tuning, and ensembles",
+    "metrics": "Classification and regression metrics",
+    "utils": "Notebook and environment utilities",
+    "text": "Text cleaning and NLP-style helpers",
+}
+
+
+def version() -> str:
+    """Return the installed dsbro version string."""
+    return __version__
+
+
+def about() -> str:
+    """Print and return basic project metadata."""
+    message = (
+        f"dsbro {__version__}\n"
+        "Your Data Science Bro. One import away.\n"
+        "Author: Muhammad Ibrahim Qasmi\n"
+        "Homepage: https://github.com/ibrahimqasmi/dsbro"
+    )
+    print(message)
+    return message
+
+
+def help(topic: str | None = None) -> str:
+    """Print a categorized help summary for dsbro modules or functions."""
+    if topic is None:
+        lines = ["dsbro available modules:"]
+        for module_name, module in _MODULES.items():
+            lines.append(f"- {module_name}: {_MODULE_SUMMARIES.get(module_name, '')}")
+            for function_name in _public_functions(module):
+                function = getattr(module, function_name)
+                signature = inspect.signature(function)
+                summary = _first_line(inspect.getdoc(function))
+                lines.append(f"  {function_name}{signature}: {summary}")
+        message = "\n".join(lines)
+        print(message)
+        return message
+
+    normalized = topic.strip().lower()
+    if normalized in _MODULES:
+        module = _MODULES[normalized]
+        lines = [f"dsbro.{normalized} - {_MODULE_SUMMARIES.get(normalized, '')}"]
+        for function_name in _public_functions(module):
+            function = getattr(module, function_name)
+            signature = inspect.signature(function)
+            summary = _first_line(inspect.getdoc(function))
+            lines.append(f"- {function_name}{signature}: {summary}")
+        message = "\n".join(lines)
+        print(message)
+        return message
+
+    for module_name, module in _MODULES.items():
+        if hasattr(module, normalized):
+            function = getattr(module, normalized)
+            message = inspect.getdoc(function) or (
+                f"No help text available for dsbro.{module_name}.{normalized}."
+            )
+            print(message)
+            return message
+
+    raise ValueError(f"Unknown help topic: {topic}")
+
+
+def _public_functions(module: Any) -> list[str]:
+    """Return public functions defined directly in a module."""
+    names: list[str] = []
+    for name, member in inspect.getmembers(module, inspect.isfunction):
+        if name.startswith("_"):
+            continue
+        if inspect.getmodule(member) is module:
+            names.append(name)
+    return sorted(names)
+
+
+def _first_line(docstring: str | None) -> str:
+    """Return the first line of a docstring."""
+    if not docstring:
+        return ""
+    return docstring.strip().splitlines()[0]
+
+
+__all__ = [
+    "__version__",
+    "about",
+    "eda",
+    "help",
+    "io",
+    "metrics",
+    "ml",
+    "prep",
+    "setup",
+    "text",
+    "utils",
+    "version",
+    "viz",
+]

dsbro-0.1.0/dsbro/_helpers.py

@@ -0,0 +1,106 @@
+"""Internal helpers used across the dsbro package."""
+
+from __future__ import annotations
+
+import ctypes
+import importlib
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+
+def _ensure_path(path: str | Path, *, exists: bool = True) -> Path:
+    """Return a normalized Path and optionally validate existence."""
+    normalized = Path(path).expanduser()
+    if exists and not normalized.exists():
+        raise FileNotFoundError(f"Path does not exist: {normalized}")
+    return normalized
+
+
+def _format_size(size_bytes: int) -> str:
+    """Format bytes into a human-readable size string."""
+    units = ["B", "KB", "MB", "GB", "TB"]
+    size = float(size_bytes)
+    for unit in units:
+        if size < 1024 or unit == units[-1]:
+            return f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size_bytes} B"
+
+
+def _safe_import(module_name: str, install_hint: str | None = None) -> Any:
+    """Import a module and raise a helpful message when missing."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError as exc:
+        message = f"Optional dependency '{module_name}' is required."
+        if install_hint:
+            message = f"{message} Install with: {install_hint}"
+        raise ImportError(message) from exc
+
+
+def _detect_text_encoding(path: Path) -> str | None:
+    """Best-effort encoding detection for small text files."""
+    for encoding in ("utf-8", "utf-8-sig", "latin-1"):
+        try:
+            path.read_text(encoding=encoding)
+            return encoding
+        except UnicodeDecodeError:
+            continue
+    return None
+
+
+def _count_lines(path: Path, encoding: str | None = None) -> int | None:
+    """Count lines in a text file."""
+    encodings = [encoding] if encoding else ["utf-8", "utf-8-sig", "latin-1"]
+    for candidate in encodings:
+        try:
+            with path.open("r", encoding=candidate) as handle:
+                return sum(1 for _ in handle)
+        except UnicodeDecodeError:
+            continue
+    return None
+
+
+def _get_package_version(name: str) -> str | None:
+    """Return an installed package version or None."""
+    try:
+        module = importlib.import_module(name)
+    except ImportError:
+        return None
+    return getattr(module, "__version__", None)
+
+
+def _get_total_memory_bytes() -> int | None:
+    """Return total system memory in bytes without requiring psutil."""
+    if hasattr(os, "sysconf"):
+        page_size = os.sysconf_names.get("SC_PAGE_SIZE")
+        page_count = os.sysconf_names.get("SC_PHYS_PAGES")
+        if page_size is not None and page_count is not None:
+            try:
+                return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+            except (OSError, ValueError):
+                pass
+
+    if platform.system() == "Windows":
+        class _MemoryStatus(ctypes.Structure):
+            _fields_ = [
+                ("length", ctypes.c_ulong),
+                ("memory_load", ctypes.c_ulong),
+                ("total_phys", ctypes.c_ulonglong),
+                ("avail_phys", ctypes.c_ulonglong),
+                ("total_page_file", ctypes.c_ulonglong),
+                ("avail_page_file", ctypes.c_ulonglong),
+                ("total_virtual", ctypes.c_ulonglong),
+                ("avail_virtual", ctypes.c_ulonglong),
+                ("avail_extended_virtual", ctypes.c_ulonglong),
+            ]
+
+        status = _MemoryStatus()
+        status.length = ctypes.sizeof(_MemoryStatus)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):
+            return int(status.total_phys)
+
+    return None
+