pycancensus 0.1.0__py3-none-any.whl

pycancensus/__init__.py

@@ -0,0 +1,52 @@
+"""
+pycancensus: Access, retrieve, and work with Canadian Census data and geography.
+
+This package provides integrated, convenient, and uniform access to Canadian
+Census data and geography retrieved using the CensusMapper API.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Dmitry Shkolnik"
+__email__ = "shkolnikd@gmail.com"
+
+from .core import get_census
+from .regions import list_census_regions, search_census_regions
+from .vectors import list_census_vectors, search_census_vectors, label_vectors
+from .datasets import list_census_datasets, dataset_attribution
+from .settings import (
+    set_api_key,
+    get_api_key,
+    set_cache_path,
+    get_cache_path,
+    remove_api_key,
+    show_api_key,
+)
+from .geometry import get_census_geometry
+from .cache import list_cache, remove_from_cache, clear_cache
+from .hierarchy import parent_census_vectors, child_census_vectors, find_census_vectors
+from .intersect_geometry import get_intersecting_geometries
+
+__all__ = [
+    "get_census",
+    "list_census_regions",
+    "search_census_regions",
+    "list_census_vectors",
+    "search_census_vectors",
+    "label_vectors",
+    "list_census_datasets",
+    "dataset_attribution",
+    "set_api_key",
+    "get_api_key",
+    "remove_api_key",
+    "show_api_key",
+    "set_cache_path",
+    "get_cache_path",
+    "get_census_geometry",
+    "list_cache",
+    "remove_from_cache",
+    "clear_cache",
+    "parent_census_vectors",
+    "child_census_vectors",
+    "find_census_vectors",
+    "get_intersecting_geometries",
+]

pycancensus/cache.py

@@ -0,0 +1,187 @@
+"""
+Caching functionality for pycancensus.
+"""
+
+import os
+import pickle
+import hashlib
+from pathlib import Path
+from typing import Any, Optional, List
+import pandas as pd
+import geopandas as gpd
+
+from .settings import get_cache_path
+
+
+def get_cached_data(cache_key: str) -> Optional[Any]:
+    """
+    Retrieve data from cache if it exists.
+
+    Parameters
+    ----------
+    cache_key : str
+        Unique identifier for the cached data.
+
+    Returns
+    -------
+    Any or None
+        Cached data if found, None otherwise.
+    """
+    cache_path = Path(get_cache_path())
+    cache_file = cache_path / f"{cache_key}.pkl"
+
+    if cache_file.exists():
+        try:
+            with open(cache_file, "rb") as f:
+                return pickle.load(f)
+        except Exception:
+            # If cache file is corrupted, remove it
+            cache_file.unlink(missing_ok=True)
+
+    return None
+
+
+def cache_data(cache_key: str, data: Any) -> None:
+    """
+    Cache data to disk.
+
+    Parameters
+    ----------
+    cache_key : str
+        Unique identifier for the data.
+    data : Any
+        Data to cache.
+    """
+    cache_path = Path(get_cache_path())
+    cache_path.mkdir(parents=True, exist_ok=True)
+
+    cache_file = cache_path / f"{cache_key}.pkl"
+
+    try:
+        with open(cache_file, "wb") as f:
+            pickle.dump(data, f)
+    except Exception as e:
+        print(f"Warning: Failed to cache data: {e}")
+
+
+def list_cache() -> pd.DataFrame:
+    """
+    List all cached data files.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with information about cached files including:
+        - cache_key: The cache key
+        - file_path: Full path to cached file
+        - size_mb: File size in MB
+        - created: Creation timestamp
+        - modified: Last modification timestamp
+
+    Examples
+    --------
+    >>> import pycancensus as pc
+    >>> cache_list = pc.list_cache()
+    >>> print(cache_list)
+    """
+    cache_path = Path(get_cache_path())
+
+    if not cache_path.exists():
+        return pd.DataFrame(
+            columns=["cache_key", "file_path", "size_mb", "created", "modified"]
+        )
+
+    cache_files = []
+
+    for cache_file in cache_path.glob("*.pkl"):
+        try:
+            stat = cache_file.stat()
+            cache_files.append(
+                {
+                    "cache_key": cache_file.stem,
+                    "file_path": str(cache_file),
+                    "size_mb": round(stat.st_size / (1024 * 1024), 2),
+                    "created": pd.Timestamp.fromtimestamp(stat.st_ctime),
+                    "modified": pd.Timestamp.fromtimestamp(stat.st_mtime),
+                }
+            )
+        except Exception:
+            continue
+
+    return pd.DataFrame(cache_files)
+
+
+def remove_from_cache(
+    cache_keys: Optional[List[str]] = None, all_cache: bool = False
+) -> None:
+    """
+    Remove items from cache.
+
+    Parameters
+    ----------
+    cache_keys : list of str, optional
+        Specific cache keys to remove. If None and all_cache=False,
+        does nothing.
+    all_cache : bool, default False
+        If True, removes all cached data.
+
+    Examples
+    --------
+    >>> import pycancensus as pc
+    >>> # Remove specific cache entries
+    >>> pc.remove_from_cache(["regions_CA16", "vectors_CA16"])
+    >>>
+    >>> # Remove all cache (use with caution!)
+    >>> pc.remove_from_cache(all_cache=True)
+    """
+    cache_path = Path(get_cache_path())
+
+    if not cache_path.exists():
+        print("No cache directory found.")
+        return
+
+    removed_count = 0
+
+    if all_cache:
+        # Remove all .pkl files
+        for cache_file in cache_path.glob("*.pkl"):
+            try:
+                cache_file.unlink()
+                removed_count += 1
+            except Exception as e:
+                print(f"Warning: Failed to remove {cache_file}: {e}")
+
+        print(f"Removed {removed_count} cached files.")
+
+    elif cache_keys:
+        # Remove specific cache keys
+        for cache_key in cache_keys:
+            cache_file = cache_path / f"{cache_key}.pkl"
+            if cache_file.exists():
+                try:
+                    cache_file.unlink()
+                    removed_count += 1
+                    print(f"Removed cache: {cache_key}")
+                except Exception as e:
+                    print(f"Warning: Failed to remove {cache_key}: {e}")
+            else:
+                print(f"Cache key not found: {cache_key}")
+
+        if removed_count > 0:
+            print(f"Removed {removed_count} cached files.")
+    else:
+        print("No cache keys specified and all_cache=False. Nothing to remove.")
+
+
+def clear_cache() -> None:
+    """
+    Clear all cached data.
+
+    This is an alias for remove_from_cache(all_cache=True).
+
+    Examples
+    --------
+    >>> import pycancensus as pc
+    >>> pc.clear_cache()
+    """
+    remove_from_cache(all_cache=True)

pycancensus/cli.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Command-line interface for pycancensus.
+"""
+
+import argparse
+import sys
+import json
+from typing import Optional
+
+import pycancensus as pc
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Access Canadian Census data through the CensusMapper API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  pycancensus datasets                    # List available datasets
+  pycancensus regions CA16                # List regions for 2016 Census
+  pycancensus vectors CA16                # List vectors for 2016 Census
+  pycancensus search-regions Vancouver CA16  # Search for Vancouver regions
+  pycancensus search-vectors income CA16     # Search for income vectors
+  
+Set API key with environment variable: export CANCENSUS_API_KEY=your_key_here
+Or get a free key at: https://censusmapper.ca/users/sign_up
+        """,
+    )
+
+    parser.add_argument(
+        "--api-key",
+        help="CensusMapper API key (or set CANCENSUS_API_KEY environment variable)",
+    )
+    parser.add_argument("--cache-path", help="Path for caching downloaded data")
+    parser.add_argument("--no-cache", action="store_true", help="Disable caching")
+    parser.add_argument("--quiet", action="store_true", help="Suppress output messages")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Datasets command
+    datasets_parser = subparsers.add_parser("datasets", help="List available datasets")
+
+    # Regions command
+    regions_parser = subparsers.add_parser("regions", help="List regions for a dataset")
+    regions_parser.add_argument("dataset", help="Dataset identifier (e.g., CA16)")
+
+    # Vectors command
+    vectors_parser = subparsers.add_parser("vectors", help="List vectors for a dataset")
+    vectors_parser.add_argument("dataset", help="Dataset identifier (e.g., CA16)")
+
+    # Search regions command
+    search_regions_parser = subparsers.add_parser(
+        "search-regions", help="Search for regions"
+    )
+    search_regions_parser.add_argument("term", help="Search term")
+    search_regions_parser.add_argument(
+        "dataset", help="Dataset identifier (e.g., CA16)"
+    )
+    search_regions_parser.add_argument("--level", help="Filter by aggregation level")
+
+    # Search vectors command
+    search_vectors_parser = subparsers.add_parser(
+        "search-vectors", help="Search for vectors"
+    )
+    search_vectors_parser.add_argument("term", help="Search term")
+    search_vectors_parser.add_argument(
+        "dataset", help="Dataset identifier (e.g., CA16)"
+    )
+    search_vectors_parser.add_argument("--type", help="Filter by vector type")
+
+    # Get data command
+    get_data_parser = subparsers.add_parser("get-data", help="Get census data")
+    get_data_parser.add_argument("dataset", help="Dataset identifier (e.g., CA16)")
+    get_data_parser.add_argument(
+        "--regions", required=True, help='Regions as JSON (e.g., \'{"CMA": "59933"}\')'
+    )
+    get_data_parser.add_argument("--vectors", help="Comma-separated list of vector IDs")
+    get_data_parser.add_argument("--level", default="Regions", help="Aggregation level")
+    get_data_parser.add_argument("--geo", action="store_true", help="Include geometry")
+    get_data_parser.add_argument("--output", help="Output file path (CSV or GeoJSON)")
+
+    args = parser.parse_args()
+
+    # Set up configuration
+    if args.api_key:
+        pc.set_api_key(args.api_key)
+
+    if args.cache_path:
+        pc.set_cache_path(args.cache_path)
+
+    use_cache = not args.no_cache
+    quiet = args.quiet
+
+    try:
+        if args.command == "datasets":
+            df = pc.list_census_datasets(use_cache=use_cache, quiet=quiet)
+            print(df.to_string(index=False))
+
+        elif args.command == "regions":
+            df = pc.list_census_regions(args.dataset, use_cache=use_cache, quiet=quiet)
+            print(df.to_string(index=False))
+
+        elif args.command == "vectors":
+            df = pc.list_census_vectors(args.dataset, use_cache=use_cache, quiet=quiet)
+            print(df.to_string(index=False))
+
+        elif args.command == "search-regions":
+            df = pc.search_census_regions(
+                args.term,
+                args.dataset,
+                level=args.level,
+                use_cache=use_cache,
+                quiet=quiet,
+            )
+            print(df.to_string(index=False))
+
+        elif args.command == "search-vectors":
+            df = pc.search_census_vectors(
+                args.term,
+                args.dataset,
+                type_filter=args.type,
+                use_cache=use_cache,
+                quiet=quiet,
+            )
+            print(df.to_string(index=False))
+
+        elif args.command == "get-data":
+            # Parse regions JSON
+            try:
+                regions = json.loads(args.regions)
+            except json.JSONDecodeError:
+                print("Error: Invalid JSON format for regions", file=sys.stderr)
+                return 1
+
+            # Parse vectors
+            vectors = None
+            if args.vectors:
+                vectors = [v.strip() for v in args.vectors.split(",")]
+
+            # Get data
+            geo_format = "geopandas" if args.geo else None
+
+            df = pc.get_census(
+                dataset=args.dataset,
+                regions=regions,
+                vectors=vectors,
+                level=args.level,
+                geo_format=geo_format,
+                use_cache=use_cache,
+                quiet=quiet,
+            )
+
+            # Output data
+            if args.output:
+                if args.output.endswith(".geojson") and hasattr(df, "to_file"):
+                    df.to_file(args.output, driver="GeoJSON")
+                    if not quiet:
+                        print(f"Data saved to {args.output}")
+                else:
+                    df.to_csv(args.output, index=False)
+                    if not quiet:
+                        print(f"Data saved to {args.output}")
+            else:
+                print(df.to_string(index=False))
+
+        else:
+            parser.print_help()
+            return 1
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if not quiet:
+            import traceback
+
+            traceback.print_exc()
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())