214 lines
5.3 KiB
Markdown
214 lines
5.3 KiB
Markdown
# surplus
|
|
|
|
Plus Code to iOS-Shortcuts-like shareable text
|
|
|
|
- [Installing](#installing)
|
|
- [Usage](#usage)
|
|
- [Command-line Interface](#command-line-interface)
|
|
- [API Reference](#api-reference)
|
|
- [surplus.surplus()](#surplussurplus)
|
|
- [surplus.parse_query()](#surplusparse_query)
|
|
- [surplus.Localcode](#surpluslocalcode)
|
|
- [surplus.Latlong](#surpluslatlong)
|
|
- [Developing](#developing)
|
|
- [The format is wrong/different!](#the-format-is-wrongdifferent)
|
|
- [Licence](#licence)
|
|
|
|
```text
|
|
$ surplus 9R3J+R9 Singapore
|
|
surplus version 1.1.1
|
|
Thomson Plaza
|
|
301 Upper Thomson Road, Bishan
|
|
574408
|
|
Singapore
|
|
```
|
|
|
|
```python
|
|
>>> 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:
|
|
|
|
```text
|
|
pip install git+https://github.com/markjoshwel/surplus
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Command-line Interface
|
|
|
|
```text
|
|
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
|
|
|
|
```python
|
|
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)
|
|
|
|
```python
|
|
# code used by surplus
|
|
location: dict[str, Any] = reverser(f"{lat}, {lon}").raw
|
|
```
|
|
|
|
dict should be similar to [nominatim raw dicts](https://nominatim.org/release-docs/latest/api/Output/#addressdetails)
|
|
|
|
- `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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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](https://www.python.org/)
|
|
- [Poetry](https://python-poetry.org/)
|
|
|
|
Alternatively, use [devbox](https://get.jetpack.io/devbox) for a hermetic development environment powered by [Nix](https://nixos.org/).
|
|
|
|
```text
|
|
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](https://github.com/markjoshwel/surplus/issues/new).
|
|
|
|
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](UNLICENCE), <http://unlicense.org/> or the Python module docstring.
|