Remote Checking

Check packages from PyPI or GitHub without local installation

Remote Checking

pycmdcheck can check packages directly from PyPI without requiring local installation. This is useful for auditing dependencies, evaluating packages before adopting them, or checking your own published packages.

Quick Start

Check a package from PyPI:

pycmdcheck remote requests

This downloads the package source distribution, extracts it to a temporary directory, runs all checks, and cleans up afterward.

Checking PyPI Packages

Latest Version

# Check the latest version
pycmdcheck remote pandas
pycmdcheck remote flask
pycmdcheck remote django

Specific Version

Use --version to check a specific release:

# Check a specific version
pycmdcheck remote requests --version 2.28.0

# Check an older version
pycmdcheck remote django --version 3.2.0

Output Formats

All standard output formats are supported:

# Rich terminal output (default)
pycmdcheck remote requests

# JSON output
pycmdcheck remote requests --format json

# GitHub Actions annotations
pycmdcheck remote requests --format github

# Markdown report
pycmdcheck remote requests --format markdown

# SARIF for security tools
pycmdcheck remote requests --format sarif

Verbose and Quiet Modes

# Show all checks including passed
pycmdcheck remote requests --verbose

# Show only failures
pycmdcheck remote requests --quiet

Use Cases

Auditing Dependencies

Before adding a new dependency, check its package quality:

# Check a potential dependency
pycmdcheck remote httpx --verbose

# Focus on security and metadata
pycmdcheck remote httpx --only-group security --only-group metadata

Comparing Versions

Check if a newer version has improved package quality:

# Check old version
pycmdcheck remote mypackage --version 1.0.0 --format json > v1.json

# Check new version
pycmdcheck remote mypackage --version 2.0.0 --format json > v2.json

# Compare (using jq or similar)
diff v1.json v2.json

Verifying Published Packages

After publishing, verify your package on PyPI:

# Verify your just-published package
pycmdcheck remote my-package --version 1.2.3

# Check with strict profile
pycmdcheck remote my-package --profile strict

CI/CD Integration

Check dependencies in your CI pipeline:

# GitHub Actions example
- name: Audit critical dependencies
  run: |
    pycmdcheck remote requests --quiet
    pycmdcheck remote pandas --quiet

How It Works

  1. Fetch Metadata: pycmdcheck queries the PyPI JSON API for package information
  2. Download Source: Downloads the source distribution (sdist) archive
  3. Extract: Extracts to a temporary directory
  4. Run Checks: Executes all configured checks against the extracted source
  5. Cleanup: Removes temporary files

Requirements

  • The package must have a source distribution (sdist) on PyPI
  • Packages with only wheel distributions cannot be checked
  • Network access to pypi.org is required

Limitations

Source Distribution Required

Remote checking requires a source distribution. Packages that only publish wheels cannot be checked:

$ pycmdcheck remote wheel-only-package
Error: Could not fetch package 'wheel-only-package'
  Package may not exist on PyPI or has no source distribution.

Network Dependency

Remote checking requires network access. For offline environments, download the package manually:

# Download manually
pip download --no-deps --no-binary :all: requests

# Extract and check locally
tar -xzf requests-*.tar.gz
pycmdcheck check requests-*/

Temporary Files

Packages are extracted to a system temporary directory. Very large packages may require significant disk space. The cleanup happens automatically, but if interrupted, temporary files may remain in your system’s temp directory.

Combining with Local Checking

Use remote checking alongside local development:

# Check your local development version
pycmdcheck check ./my-package

# Compare with published version
pycmdcheck remote my-package --version 1.0.0 --format json > published.json
pycmdcheck check ./my-package --format json > local.json

# See what's different
diff published.json local.json

Python API

For programmatic access:

from pathlib import Path
from pycmdcheck.remote import RemotePackageFetcher

# Create fetcher
fetcher = RemotePackageFetcher(timeout=30.0)

try:
    # Fetch from PyPI
    package_path = fetcher.fetch_from_pypi("requests", version="2.28.0")

    if package_path:
        print(f"Package extracted to: {package_path}")

        # Run checks on the extracted package
        from pycmdcheck import check
        results = check(package_path)
        print(f"Passed: {results.passed}, Failed: {results.failed}")
    else:
        print("Failed to fetch package")
finally:
    # Always cleanup temporary directories
    fetcher.cleanup()

Fetching from URLs

You can also fetch from direct URLs:

# Fetch from a direct URL
package_path = fetcher.fetch_from_url(
    "https://example.com/package-1.0.0.tar.gz"
)

Supported archive formats:

  • .tar.gz / .tgz
  • .zip

Error Handling

Package Not Found

$ pycmdcheck remote nonexistent-package
Error: Could not fetch package 'nonexistent-package'
  Package may not exist on PyPI.

Version Not Found

$ pycmdcheck remote requests --version 99.99.99
Error: Could not fetch package 'requests'
  Version 99.99.99 may not exist on PyPI.

Network Errors

$ pycmdcheck remote requests
Error: Connection timeout
  Check your network connection and try again.

Tips

  1. Use --quiet for batch checking - When checking multiple packages, quiet mode shows only failures

  2. Cache results - Save JSON output to compare versions over time

  3. Check before publishing - Use local check before pip upload, then verify with remote check after

  4. Audit dependencies regularly - Include remote checks in your CI/CD to catch dependency issues early

  5. Use specific versions - Pin versions when auditing for reproducibility