surplus/README.md

surplus

Plus Code to iOS-Shortcuts-like shareable text

• Installing
• Usage
  • Command-line Interface
  • API Reference
    • surplus.surplus()
    • surplus.parse_query()
    • surplus.Localcode
    • surplus.Latlong
• Developing
• The format is wrong/different!
• Licence

$ 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:

• Python >=3.10
• Poetry

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.