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

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.