Merge pull request #36 from HzaCode/pyopensci-review

pyOpenSci review improvements

Author: HzaCode

.github/workflows/tests.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install ".[dev,plot]" pytest-cov coverage-badge
+          pip install ".[dev,plot]" pytest-cov coverage-badge mypy types-requests
 
       - name: Verify plotting libraries
         run: |
@@ -37,6 +37,14 @@ jobs:
           print("matplotlib", matplotlib.__version__)
           PY
 
+      - name: Run linting with ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Run type checking with mypy
+        run: mypy src/ChemInformant --ignore-missing-imports --allow-untyped-defs --allow-incomplete-defs --no-strict-optional
+
       - name: Run tests with coverage
         env:
           PYTHONPATH: ${{ github.workspace }}/src

README.md

@@ -18,7 +18,7 @@
         <img src="https://img.shields.io/pypi/v/ChemInformant.svg" alt="PyPI version">
     </a>
     <a href="https://pypi.org/project/ChemInformant/">
-        <img src="https://img.shields.io/badge/python-%3E%3D3.8-blue.svg" alt="Python Version">
+        <img src="https://img.shields.io/badge/python-%3E%3D3.9-blue.svg" alt="Python Version">
     </a>
     <a href="https://github.com/HzaCode/ChemInformant/blob/main/LICENSE.md">
         <img src="https://img.shields.io/pypi/l/ChemInformant.svg" alt="License">
@@ -27,7 +27,10 @@
 
 <p>
     <a href="https://github.com/HzaCode/ChemInformant/actions/workflows/tests.yml">
-        <img src="https://img.shields.io/github/actions/workflow/status/HzaCode/ChemInformant/tests.yml?label=Build" alt="Build Status">
+        <img src="https://img.shields.io/github/actions/workflow/status/HzaCode/ChemInformant/tests.yml?label=Tests" alt="Tests Status">
+    </a>
+    <a href="https://github.com/HzaCode/ChemInformant/actions/workflows/docs-deploy.yml">
+        <img src="https://img.shields.io/github/actions/workflow/status/HzaCode/ChemInformant/docs-deploy.yml?label=Docs" alt="Docs Build Status">
     </a>
     <a href="https://cdn.jsdelivr.net/gh/HzaCode/ChemInformant@gh-pages/coverage.svg">
         <img src="https://cdn.jsdelivr.net/gh/HzaCode/ChemInformant@gh-pages/coverage.svg" alt="coverage">
@@ -170,7 +173,15 @@ For a deep dive, please see our detailed guides:
 
 *   **➡️ Online Documentation:** The **[official documentation site](https://hezhiang.com/ChemInformant)** contains complete API references, guides, and usage examples. **This is the most comprehensive resource.**
 *   **➡️ Interactive User Manual:** Our [**Jupyter Notebook Tutorial**](examples/ChemInformant_User_Manual_v1.0.ipynb) provides a complete, end-to-end walkthrough. This is the best place to start for a hands-on experience.
-*   **➡️ Performance Benchmarks:** You can review and run our [**Benchmark Script**](./benchmark.py) to see the performance advantages of batching and caching.
+*   **➡️ Performance Benchmarks:** Run integrated benchmarks with `pytest tests/test_benchmarks.py --benchmark-only` to see the performance advantages of batching and caching.
+
+#### 📖 Additional Resources & Use Cases
+
+*   **[Basic Usage Guide](https://hezhiang.com/ChemInformant/basic_usage.html)** - Quick start examples for common tasks
+*   **[Advanced Usage Guide](https://hezhiang.com/ChemInformant/advanced_usage.html)** - Complex workflows and batch processing
+*   **[Caching Guide](https://hezhiang.com/ChemInformant/caching_guide.html)** - Optimize performance with intelligent caching
+*   **[CLI Tools Documentation](https://hezhiang.com/ChemInformant/cli.html)** - Complete reference for `chemfetch` and `chemdraw`
+*   **[API Reference](https://hezhiang.com/ChemInformant/api/)** - Full function documentation with examples
 
 ---
 

benchmark.py

@@ -1,5 +1,6 @@
 sphinx
 sphinx-rtd-theme
+sphinx-copybutton
 
-# myst-parser
-# sphinx-copybutton
+# Required for consistent syntax highlighting
+pygments>=2.17.0

docs/requirements.txt

@@ -20,12 +20,30 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx_copybutton",
 ]
 
 templates_path   = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 source_suffix    = ".rst"
-pygments_style   = "sphinx"
+pygments_style   = "default"
+
+# -- Syntax highlighting configuration ----------------------------------------
+# Ensure consistent syntax highlighting across all code blocks
+highlight_language = "python"
+highlight_options = {
+    'default': {'stripall': False},
+    'python': {'stripall': False},
+    'bash': {'stripall': False},
+    'text': {'stripall': False},
+}
+
+# -- Copy button configuration -----------------------------------------------
+# Configure sphinx-copybutton to skip prompts and output
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = False
+copybutton_remove_prompts = True
 
 # -- HTML output --------------------------------------------------------------
 html_theme       = "sphinx_rtd_theme"

docs/source/conf.py

@@ -53,7 +53,7 @@ If you wish to get the latest, unreleased development version, or if you plan to
     *   **To set up a complete environment for development contribution:**
         This command will install all dependencies, including the core library, plotting functionality, and development tools for testing and code checking (like `pytest`, `black`). This is the recommended command for contributors.
 
-        .. code-tally-block:: bash
+        .. code-block:: bash
 
            pip install -e .[all]
 

docs/source/installation.rst

@@ -14,15 +14,15 @@ authors = [
 ]
 description = "A robust and high-throughput Python client for the PubChem API, designed for automated data retrieval and analysis"
 readme = { file = "README.md", content-type = "text/markdown" }
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 license = "MIT"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Operating System :: OS Independent",
     "Topic :: Scientific/Engineering :: Chemistry",
 ]
@@ -71,7 +71,9 @@ dev = [
     "pytest>=7.0",
     "pytest-mock>=3.5",
     "pytest-cov>=2.12",
-    "ruff"
+    "pytest-benchmark>=4.0",
+    "ruff",
+    "mypy"
 ]
 
 [tool.setuptools.packages.find]
@@ -86,7 +88,7 @@ source = ["ChemInformant"]
 [tool.ruff]
 # Set line length to match black formatter
 line-length = 88
-target-version = "py38"
+target-version = "py39"
 
 [tool.ruff.lint]
 # Enabled rule sets, replacing multiple tools:
@@ -103,6 +105,9 @@ select = ["E", "W", "F", "I", "N", "UP", "B", "C4", "SIM"]
 # Ignored rules
 ignore = [
     "E501",  # Line length handled by formatter
+    "N999",  # Invalid module name (ChemInformant is a valid name)
+    "N813",  # Camelcase imported as lowercase (common for packages)
+    "SIM117", # Multiple context managers (sometimes clearer as nested)
 ]
 
 [tool.ruff.lint.isort]
@@ -115,3 +120,32 @@ quote-style = "double"
 indent-style = "space"
 skip-magic-trailing-comma = false
 line-ending = "auto"
+
+# ---------------------------
+#  MyPy configuration
+# ---------------------------
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = [
+    "requests_cache.*",
+    "pubchempy.*",
+    "matplotlib.*",
+    "seaborn.*",
+    "sklearn.*",
+    "PIL.*"
+]
+ignore_missing_imports = true

pyproject.toml

@@ -0,0 +1,23 @@
+[tool:pytest-benchmark]
+# Benchmark configuration for ChemInformant
+min_rounds = 3
+max_time = 30.0
+min_time = 0.1
+timer = time.perf_counter
+disable_gc = true
+warmup = true
+warmup_iterations = 2
+
+# Output options
+sort = mean
+columns = min,max,mean,stddev,rounds,iterations
+histogram = true
+
+# Save results
+save = .benchmarks
+save-data = true
+autosave = true
+
+# Compare with previous runs
+compare = 0001
+compare-fail = mean:10%