surplus/README.md
2023-06-16 05:19:19 +00:00

5.3 KiB

surplus

Plus Code to iOS-Shortcuts-like shareable text

$ surplus 9R3J+R9 Singapore
surplus version 1.1.1
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: typing.Callable = geopy.geocoders.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: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser
      latlong to location function, accesses a dict from .raw attribute of return object function should be able to take a string with two floats and return a geopy.Location-like object (None checking is done)

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

      dict should be similar to nominatim 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, debug: bool = False
    ) -> 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, geocoder: Callable = Nominatim(user_agent="surplus").geocode
    ) -> tuple[bool, str]:
    
  • arguments:

    • geocoder: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").geocode
      place/locality to location function, accesses .longitude and .latitude if returned object is not None
  • 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.