Plus Code/latlong/query to iOS-Shortcuts-like shareable text
Go to file
Mark Joshwel a61a80d8c1 docs: many (#1)
- fix/update table of contents
- add api reference
- add wrong format contrib guide
- update usage and examples
2023-06-03 08:31:02 +00:00
.github/workflows ci: update jetbox gh action to 0.3.0 2023-06-03 07:46:55 +00:00
.gitignore meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00
devbox.json meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00
devbox.lock meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00
poetry.lock meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00
pyproject.toml meta: add s+ console script (#1) 2023-06-03 08:26:15 +00:00
README.md docs: many (#1) 2023-06-03 08:31:02 +00:00
requirements.txt meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00
surplus.py code: lint 2023-06-02 19:50:46 +00:00
UNLICENCE meta: add files, 1.0.0 2023-06-02 19:39:25 +00:00

surplus

Plus Code to iOS-Shortcuts-like shareable text

$ surplus 6PH59R3J+R9
surplus version 1.0.0
Thomson Plaza
301 Upper Thomson Road, Bishan
574408
Singapore
>>> from surplus import surplus, Localcode
>>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
(True, '6PH58RPQ+JW')
>>> surplus("6PH58RPQ+JW")
(True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nSingapore')

Installing

Install surplus directly from GitHub using pip:

pip install git+https://github.com/markjoshwel/surplus

Usage

Command-line Interface

usage: surplus [-h] [-d] query

Plus Code to iOS-Shortcuts-like shareable text

positional arguments:
  query        full-length Plus Code (6PH58QMF+FX), local codes (8QMF+FX Singapore), or latlong (1.3336875, 103.7749375)

options:
  -h, --help   show this help message and exit
  -d, --debug  prints lat, long and reverser response dict to stderr

API Reference

surplus.surplus()

pluscode to shareable text conversion function

  • signature

    def surplus(
        query: str | Localcode | Latlong,
        reverser: Callable = Nominatim(user_agent="surplus").reverse,
        debug: bool = False,
    ) -> tuple[bool, str]:
      ...
    
  • arguments

    • query: str | surplus.Localcode | surplus.Latlong
      str - normal longcode (6PH58QMF+FX) surplus.Localcode - shortcode with locality (8QMF+FX Singapore) surplus.Latlong - latlong

    • reverser: Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser
      latlong to data function, accesses a dict from .raw attribute of return object function should be able to take a string with two floats

      # code used by surplus
      location: dict[str, Any] = reverser(f"{lat}, {lon}").raw
      

      dict should be similar to geopy's geocoder provider .raw dicts

    • debug: bool = False
      prints lat, long and reverser response dict to stderr

  • returns tuple[bool, str]

    • (True, <str>)
      conversion was successful, str is resultant text
    • (False, <str>)
      conversion failed, str is error message

surplus.parse_query()

function that parses a string Plus Code, local code or latlong into a str, surplus.Localcode or surplus.Latlong respectively

  • signature:

    def parse_query(query: str) -> tuple[bool, str | Localcode | Latlong]:
    
  • arguments:

    • query: str
      string Plus Code, local code or latlong
  • returns tuple[bool, str | Localcode | Latlong]

    • (True, <str | Localcode | Latlong>)
      conversion was successful, second element is result
    • (False, <str>)
      conversion failed, str is error message

surplus.Localcode

typing.NamedTuple representing short Plus Code with locality

  • parameters:

    • code: str Plus Code - e.g.: "8QMF+FX"
    • locality: str e.g.: "Singapore"

surplus.Localcode.full_length()

method that calculates full-length Plus Code using locality

  • signature:

    def full_length(self) -> tuple[bool, str]:
    
  • returns:

    • (True, <str>)
      conversion was successful, str is resultant Plus Code
    • (False, <str>)
      conversion failed, str is error message

surplus.Latlong

typing.NamedTuple representing a pair of latitude and longitude coordinates

  • parameters:

    • lat: float
      latitudinal coordinate
    • long: float
      longitudinal coordinate

Developing

Prerequisites:

Alternatively, use devbox for a hermetic development environment powered by Nix.

devbox shell    # skip this if you aren't using devbox
poetry install
poetry shell

The format is wrong/different!

If surplus generates wrong text for a particular Plus Code, submit an issue.

Ensure you detail the following:

  1. The erroneous Plus Code, local code or latlong, or a similar coordinate that reproduces the same error

  2. Output from the terminal, with --debug enabled or debug=True

  3. How it should look like instead

Licence

surplus is free and unencumbered software released into the public domain. For more information, please refer to the UNLICENCE, http://unlicense.org/ or the Python module docstring.