Naming conventions for kashima.mapper

This document defines a minimal and explicit naming policy for functions, classes, modules, and variables in kashima.mapper. Goals:

  • Clearly separate public API vs internal helpers.
  • Preserve backward compatibility.
  • Avoid chaotic naming and mixed-language identifiers.

1. Public API surface

The public API of kashima.mapper is defined by what is exported in kashima/mapper/__init__.py. Today it includes:

1.1 Public classes

  • MapConfig
  • EventConfig
  • FaultConfig
  • StationConfig
  • USGSCatalog
  • GCMTCatalog
  • EventMap

1.2 Public functions and constants

  • buildMap
  • buildCatalog
  • buildUSGSCatalog
  • buildGCMTCatalog
  • buildISCCatalog
  • buildGEMActiveFaults
  • buildUSGSQuaternaryFaults
  • buildEFSM20Faults
  • downloadAllCatalogs
  • updateAllCatalogs
  • updateUSGSCatalog
  • updateGCMTCatalog
  • updateISCCatalog
  • updateGEMActiveFaults
  • updateUSGSQuaternaryFaults
  • updateEFSM20Faults
  • get_cache_dir
  • clear_cache
  • get_auxiliary_file_path
  • auxiliary_file_exists
  • calculate_zoom_level
  • EARTH_RADIUS_KM
  • TILE_LAYERS

These entries define the stable surface of kashima.mapper. Renaming work must not break these imports. BaseMap, BlastConfig, and BlastCatalog are not part of the active mapper API from version 3.2.0 onward.

2. Rules for public functions

  1. Keep the historical camelCase style for high-level public functions:
    • buildMap, buildCatalog, downloadAllCatalogs, updateAllCatalogs, etc.

  2. If snake_case equivalents are introduced in the future, they must be aliases and not replacements. Hypothetical example:

    def build_map(*args, **kwargs):
    """snake_case alias for buildMap (compatibility)."""
    return buildMap(*args, **kwargs)
  3. Documentation (README and docs/) must always refer to public functions by their exact names.

3. Rules for classes

  1. All public classes (including config classes) use PascalCase.
  2. Internal classes should also use PascalCase.

4. Modules and internal helpers

  1. Module names should use short English snake_case:
    • Good: event_map.py, site_marker.py, local_faults.py
  2. Internal functions use snake_case and should use a _ prefix when private to a module.
  3. Avoid overly long or informal names.
  4. Internal code identifiers should be English.

5. Variables and parameters

  1. User-facing parameters should use readable, stable snake_case.
  2. Internal variables should also use snake_case; standard abbreviations are OK when clear (df, gdf, bbox).

6. Constants

  1. Global constants use ALL_CAPS with _.
  2. Shared constants should live in one place and be imported where needed.

7. Refactor strategy

  1. Inventory: review kashima/mapper/__init__.py and classify symbols.
  2. Module-by-module internal refactors: rename only internal helpers first.
  3. Documentation: update README/docs if aliases are introduced or names are deprecated.

This document is the reference for naming changes starting from kashima 1.7.0.