ssdownload 0.1.0__tar.gz

ssdownload-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.vscode/
+.pytest_cache/
+.ruff_cache/
+.venv/
+test_output/
+matrices
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache
+nosetests.xml
+coverage.xml
+*.egg-info/
+build/
+dist/
+
+# Test artifacts
+.hypothesis/
+ssstats_cache.json

ssdownload-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Suguru Kurita
+
+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.

ssdownload-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: ssdownload
+Version: 0.1.0
+Summary: Download sparse matrices from SuiteSparse Matrix Collection
+Author-email: Suguru Kurita <skurita0208@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.4.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.26.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SuiteSparse Matrix Collection Downloader
+
+**Modern Python tool for downloading sparse matrices from the [SuiteSparse Matrix Collection](https://sparse.tamu.edu/)**
+
+> ⚠️ **This project is under active development.** APIs and features may change without notice.
+
+A command-line tool and Python library that makes it easy to discover, download, and work with sparse matrices from the world's largest collection of sparse matrix data.
+
+## ✨ Features
+
+- 🔍 **Smart Matrix Discovery** - Search by size, sparsity, mathematical properties, and more
+- 📦 **Multiple Formats** - Download MAT-files, Matrix Market, or Rutherford-Boeing formats
+- ⚡ **Concurrent Downloads** - Up to 8 parallel downloads with progress tracking
+- 🔄 **Resume Support** - Interrupted downloads continue automatically
+- ✅ **Integrity Verification** - MD5 checksum validation ensures data accuracy
+- 🧠 **Smart Caching** - Skip re-downloads of existing files
+- 🎨 **Rich CLI** - Beautiful progress bars and colored output
+- 🔧 **Type Safety** - Full type hints for better IDE support
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone and install (not yet on PyPI)
+git clone <repository-url>
+cd ssdownload
+curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
+uv sync                                           # Install dependencies
+```
+
+#### Global Installation (Recommended for Development)
+
+For easier command usage without `uv run` prefix:
+
+```bash
+# From project root (or use absolute path)
+uv tool install .          # Initial installation
+uv tool update-shell       # Update PATH (first time only)
+
+# Verify installation
+ssdl --help
+
+# After code changes
+uv tool upgrade ssdownload --reinstall   # Update wrapper only
+```
+
+### Basic Usage
+
+> **Command Format**: Use `ssdl` directly if you've done global installation, otherwise add `uv run` prefix.
+
+```bash
+# Get matrix information
+ssdl info ct20stif
+
+# Download a matrix (auto-detects group)
+ssdl download ct20stif
+
+# Download in Matrix Market format
+ssdl download ct20stif --format mm
+
+# Search matrices with filters
+ssdl list --spd --size 1000:10000 --field real
+
+# Bulk download (real) SPD matrices in size range
+ssdl bulk --spd --field real --size 100:1000 --max-files 5
+```
+
+<details>
+<summary>Python API Example</summary>
+
+```python
+from ssdownload import SuiteSparseDownloader, Filter
+
+# Simple download
+downloader = SuiteSparseDownloader()
+path = await downloader.download_by_name("ct20stif")
+
+# Filtered bulk download
+filter_obj = Filter(spd=True, n_rows=(1000, 10000))
+paths = await downloader.bulk_download(filter_obj, max_files=5)
+```
+
+</details>
+
+## 📚 Documentation
+
+- **[Installation Guide](docs/INSTALLATION.md)** - Detailed setup instructions
+- **[CLI Reference](docs/CLI_REFERENCE.md)** - Complete command-line options
+- **[Python API](docs/API_REFERENCE.md)** - Full API documentation
+- **[Examples](docs/EXAMPLES.md)** - Usage examples and tutorials
+- **[Development](docs/DEVELOPMENT.md)** - Contributing and development setup
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Development Guide](docs/DEVELOPMENT.md) for setup instructions and coding standards.
+
+1. Fork the repository
+2. Create your feature branch
+3. Add tests for new functionality
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [SuiteSparse Matrix Collection](https://sparse.tamu.edu/) by [Tim Davis](https://people.engr.tamu.edu/davis/)
+- Built with [httpx](https://www.python-httpx.org/), [Rich](https://rich.readthedocs.io/), and [Typer](https://typer.tiangolo.com/)

ssdownload-0.1.0/README.md

@@ -0,0 +1,112 @@
+# SuiteSparse Matrix Collection Downloader
+
+**Modern Python tool for downloading sparse matrices from the [SuiteSparse Matrix Collection](https://sparse.tamu.edu/)**
+
+> ⚠️ **This project is under active development.** APIs and features may change without notice.
+
+A command-line tool and Python library that makes it easy to discover, download, and work with sparse matrices from the world's largest collection of sparse matrix data.
+
+## ✨ Features
+
+- 🔍 **Smart Matrix Discovery** - Search by size, sparsity, mathematical properties, and more
+- 📦 **Multiple Formats** - Download MAT-files, Matrix Market, or Rutherford-Boeing formats
+- ⚡ **Concurrent Downloads** - Up to 8 parallel downloads with progress tracking
+- 🔄 **Resume Support** - Interrupted downloads continue automatically
+- ✅ **Integrity Verification** - MD5 checksum validation ensures data accuracy
+- 🧠 **Smart Caching** - Skip re-downloads of existing files
+- 🎨 **Rich CLI** - Beautiful progress bars and colored output
+- 🔧 **Type Safety** - Full type hints for better IDE support
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone and install (not yet on PyPI)
+git clone <repository-url>
+cd ssdownload
+curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
+uv sync                                           # Install dependencies
+```
+
+#### Global Installation (Recommended for Development)
+
+For easier command usage without `uv run` prefix:
+
+```bash
+# From project root (or use absolute path)
+uv tool install .          # Initial installation
+uv tool update-shell       # Update PATH (first time only)
+
+# Verify installation
+ssdl --help
+
+# After code changes
+uv tool upgrade ssdownload --reinstall   # Update wrapper only
+```
+
+### Basic Usage
+
+> **Command Format**: Use `ssdl` directly if you've done global installation, otherwise add `uv run` prefix.
+
+```bash
+# Get matrix information
+ssdl info ct20stif
+
+# Download a matrix (auto-detects group)
+ssdl download ct20stif
+
+# Download in Matrix Market format
+ssdl download ct20stif --format mm
+
+# Search matrices with filters
+ssdl list --spd --size 1000:10000 --field real
+
+# Bulk download (real) SPD matrices in size range
+ssdl bulk --spd --field real --size 100:1000 --max-files 5
+```
+
+<details>
+<summary>Python API Example</summary>
+
+```python
+from ssdownload import SuiteSparseDownloader, Filter
+
+# Simple download
+downloader = SuiteSparseDownloader()
+path = await downloader.download_by_name("ct20stif")
+
+# Filtered bulk download
+filter_obj = Filter(spd=True, n_rows=(1000, 10000))
+paths = await downloader.bulk_download(filter_obj, max_files=5)
+```
+
+</details>
+
+## 📚 Documentation
+
+- **[Installation Guide](docs/INSTALLATION.md)** - Detailed setup instructions
+- **[CLI Reference](docs/CLI_REFERENCE.md)** - Complete command-line options
+- **[Python API](docs/API_REFERENCE.md)** - Full API documentation
+- **[Examples](docs/EXAMPLES.md)** - Usage examples and tutorials
+- **[Development](docs/DEVELOPMENT.md)** - Contributing and development setup
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Development Guide](docs/DEVELOPMENT.md) for setup instructions and coding standards.
+
+1. Fork the repository
+2. Create your feature branch
+3. Add tests for new functionality
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [SuiteSparse Matrix Collection](https://sparse.tamu.edu/) by [Tim Davis](https://people.engr.tamu.edu/davis/)
+- Built with [httpx](https://www.python-httpx.org/), [Rich](https://rich.readthedocs.io/), and [Typer](https://typer.tiangolo.com/)

ssdownload-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ssdownload"
+version = "0.1.0"
+description = "Download sparse matrices from SuiteSparse Matrix Collection"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "Suguru Kurita", email = "skurita0208@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "typer>=0.9.0",
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+    "tqdm>=4.66.0",
+    "beautifulsoup4>=4.12.0",
+    "platformdirs>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-httpx>=0.26.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "pre-commit>=3.5.0",
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.4.0",
+]
+
+[project.scripts]
+ssdl = "ssdownload.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ssdownload"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501", # line too long, handled by black
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+markers = [
+    "slow: marks tests as slow (requiring network access or file I/O)",
+    "integration: marks tests as integration tests with real API calls",
+    "contract: marks tests as contract tests for API response format",
+    "property: marks property-based tests with Hypothesis",
+    "e2e: marks end-to-end workflow tests",
+    "performance: marks performance and load tests",
+]
+addopts = [
+    "--strict-markers",
+    "--disable-warnings",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.0.0",
+    "pytest-httpx>=0.35.0",
+    "mypy>=1.0.0",
+    "pytest-cov>=4.0.0",
+    "pre-commit>=4.2.0",
+    "hypothesis>=6.135.16",
+]

ssdownload-0.1.0/src/ssdownload/__init__.py

@@ -0,0 +1,24 @@
+"""SuiteSparse Matrix Collection Downloader."""
+
+from .client import SuiteSparseDownloader
+from .exceptions import (
+    ChecksumError,
+    DownloadError,
+    IndexError,
+    MatrixNotFoundError,
+    NetworkError,
+    SSDownloadError,
+)
+from .filters import Filter
+
+__all__ = [
+    "SuiteSparseDownloader",
+    "Filter",
+    "SSDownloadError",
+    "ChecksumError",
+    "MatrixNotFoundError",
+    "IndexError",
+    "DownloadError",
+    "NetworkError",
+]
+__version__ = "0.1.0"