docs: readme rewrite (#16)
This commit is contained in:
parent
e519901bb8
commit
ccb4119fdf
458
README.md
458
README.md
|
|
@ -1,19 +1,19 @@
|
||||||
# surplus
|
# surplus
|
||||||
|
|
||||||
Plus Code to iOS-Shortcuts-like shareable text
|
surplus is a Python script to convert
|
||||||
|
[Google Map Plus Codes](https://maps.google.com/pluscodes/)
|
||||||
|
to iOS Shortcuts-like human text.
|
||||||
|
|
||||||
- [Installing](#installing)
|
- [installation](#installation)
|
||||||
- [Usage](#usage)
|
- [command-line usage](#command-line-usaage)
|
||||||
- [Command-line Interface](#command-line-interface)
|
- [developer's guide](#developers-guide)
|
||||||
- [API Reference](#api-reference)
|
- [api reference](#api-reference)
|
||||||
- [surplus.surplus()](#surplussurplus)
|
- [contributor's guide](#contributors-guide)
|
||||||
- [surplus.parse_query()](#surplusparse_query)
|
- [reporting incorrect output](#reporting-incorrect-output)
|
||||||
- [surplus.handle_query()](#surplushandle_query)
|
- [the reporting process](#the-reporting-process)
|
||||||
- [surplus.Localcode](#surpluslocalcode)
|
- [what counts as "incorrect"](#what-counts-as-incorrect)
|
||||||
- [surplus.Latlong](#surpluslatlong)
|
- [output technical details](#the-technical-details-of-surpluss-output)
|
||||||
- [Developing](#developing)
|
- [licence](#licence)
|
||||||
- [The format is wrong/different!](#the-format-is-wrongdifferent)
|
|
||||||
- [Licence](#licence)
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
$ surplus 9R3J+R9 Singapore
|
$ surplus 9R3J+R9 Singapore
|
||||||
|
|
@ -33,17 +33,15 @@ Central, Singapore
|
||||||
(True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nCentral, Singapore')
|
(True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nCentral, Singapore')
|
||||||
```
|
```
|
||||||
|
|
||||||
## Installing
|
## installation
|
||||||
|
|
||||||
Install surplus directly from GitHub using pip:
|
install surplus directly from the repository using pip:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
pip install git+https://github.com/markjoshwel/surplus
|
pip install git+https://github.com/markjoshwel/surplus
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
## command-line usage
|
||||||
|
|
||||||
### Command-line Interface
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
usage: surplus [-h] [-d] [-v] [query ...]
|
usage: surplus [-h] [-d] [-v] [query ...]
|
||||||
|
|
@ -63,9 +61,370 @@ options:
|
||||||
and exits
|
and exits
|
||||||
```
|
```
|
||||||
|
|
||||||
### API Reference
|
## developer's guide
|
||||||
|
|
||||||
#### `surplus.surplus()`
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
## contributor's guide
|
||||||
|
|
||||||
|
1. fork the repository and branch off from the `future` branch
|
||||||
|
2. make and commit your changes!
|
||||||
|
3. pull in any changes from `future`, and resolve any conflicts, if any
|
||||||
|
4. **commit your copyright waiver** (_see below_)
|
||||||
|
5. submit a pull request (_or mail in a diff_)
|
||||||
|
|
||||||
|
when contributing your first changes, please include an empty commit for a copyright
|
||||||
|
waiver using the following message (replace 'Your Name' with your name or nickname):
|
||||||
|
|
||||||
|
```
|
||||||
|
Your Name Copyright Waiver
|
||||||
|
|
||||||
|
I dedicate any and all copyright interest in this software to the
|
||||||
|
public domain. I make this dedication for the benefit of the public at
|
||||||
|
large and to the detriment of my heirs and successors. I intend this
|
||||||
|
dedication to be an overt act of relinquishment in perpetuity of all
|
||||||
|
present and future rights to this software under copyright law.
|
||||||
|
```
|
||||||
|
|
||||||
|
the command to create an empty commit is `git commit --allow-empty`
|
||||||
|
|
||||||
|
### reporting incorrect output
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
> this section is independent from the rest of the contributing section.
|
||||||
|
|
||||||
|
different output from the iOS Shortcuts app is expected, however incorrect output is not.
|
||||||
|
|
||||||
|
#### the reporting process
|
||||||
|
|
||||||
|
open an issue in the
|
||||||
|
[repositories issue tracker](https://github.com/markjoshwel/surplus/issues/new),
|
||||||
|
and include the following:
|
||||||
|
|
||||||
|
1. ensure that your issue is not an error of incorrect data returned by your reverser
|
||||||
|
function, which by default is OpenStreetMap Nominatim.
|
||||||
|
(_don't know what the above means? then using the default reverser._)
|
||||||
|
|
||||||
|
also look at "[what counts as 'incorrect'](#what-counts-as-incorrect)" before
|
||||||
|
moving on.
|
||||||
|
|
||||||
|
2. include the erroneous Plus Code, local code, latitude and longitude coordinate, or
|
||||||
|
query string.
|
||||||
|
|
||||||
|
3. include output from the teminal with the
|
||||||
|
[`--debug` flag](#command-line-usage) passed to the surplus CLI or with
|
||||||
|
`debug=True` set in function calls.
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
> if you are using custom stdout and stderr parameters and redirecting output,
|
||||||
|
> include that instead.
|
||||||
|
|
||||||
|
4. how it should look like instead, with reasoning if the error not obvious. (e.g., missing details)
|
||||||
|
|
||||||
|
for reference, see how the following issues were written:
|
||||||
|
|
||||||
|
- [issue #4: "Incorrect format: repeated lines"](https://github.com/markjoshwel/surplus/issues/4)
|
||||||
|
- [issue #6: "Incorrect format: missing details"](https://github.com/markjoshwel/surplus/issues/6)
|
||||||
|
- [issue #12: "Incorrect format: State before county"](https://github.com/markjoshwel/surplus/issues/12)
|
||||||
|
|
||||||
|
#### what counts as "incorrect"
|
||||||
|
|
||||||
|
- **example 1**
|
||||||
|
|
||||||
|
- iOS Shortcuts Output
|
||||||
|
|
||||||
|
```
|
||||||
|
Plaza Singapura
|
||||||
|
68 Orchard Rd
|
||||||
|
238839
|
||||||
|
Singapore
|
||||||
|
```
|
||||||
|
|
||||||
|
- surplus Output
|
||||||
|
|
||||||
|
```
|
||||||
|
Plaza Singapura
|
||||||
|
68 Orchard Road
|
||||||
|
Museum
|
||||||
|
238839
|
||||||
|
Central, Singapore
|
||||||
|
```
|
||||||
|
|
||||||
|
this _should not_ be reported as incorrect, as the only difference between the two is
|
||||||
|
that surplus displays more information.
|
||||||
|
|
||||||
|
note: for singaporean readers, "Musuem" here is correct as it refers to the
|
||||||
|
[Museum planning area](https://en.wikipedia.org/wiki/Museum_Planning_Area),
|
||||||
|
in which Plaza Singapura is located in.
|
||||||
|
|
||||||
|
other examples that _should not_ be reported are:
|
||||||
|
|
||||||
|
- name of place is incorrect/different
|
||||||
|
|
||||||
|
this may be due to incorrect data from the geolocator function, which is OpenStreetMap Nominatim by default.
|
||||||
|
in the case of Nominatim, it means that there the data on OpenStreetMap is incorrect.
|
||||||
|
|
||||||
|
(_if so, then consider updating OpenStreetMap to help not just you, but other surplus
|
||||||
|
and OpenStreetMap users!_)
|
||||||
|
|
||||||
|
you should report when the output does not make logical sense, or something similar
|
||||||
|
wherein the output of surplus is illogical to read or is not correct in the traditional
|
||||||
|
sense of a correct address.
|
||||||
|
|
||||||
|
see the linked issues in [the reporting process](#the-reporting-process) for examples
|
||||||
|
of incorrect outputs.
|
||||||
|
|
||||||
|
## the technical details of surplus's output
|
||||||
|
|
||||||
|
```
|
||||||
|
$ s+ 8QJF+RP --debug
|
||||||
|
surplus version 1.1.3, debug mode
|
||||||
|
debug: args.query='8QJF+RP Singapore'
|
||||||
|
debug: squery=['8QJF+RP', 'Singapore']
|
||||||
|
debug: pcode='8QJF+RP', locality='Singapore'
|
||||||
|
debug: lat=1.3320625, lon=103.7743125
|
||||||
|
debug: location={...}
|
||||||
|
debug: seen_names=['Ngee Ann Polytechnic', '', '', '']
|
||||||
|
debug: d='' _dvtm4=[False, False, False, False] _dvcm4=[False, False, False, False]
|
||||||
|
debug: d='Bukit Timah' _dvtm4=[True, True, True, True] _dvcm4=[True, True, True, True]
|
||||||
|
debug: d='Singapore' _dvtm4=[True, True, False, True] _dvcm4=[True, True, True, True]
|
||||||
|
0 Ngee Ann Polytechnic
|
||||||
|
1
|
||||||
|
2
|
||||||
|
3 535 Clementi Road
|
||||||
|
4 Bukit Timah
|
||||||
|
5 599489
|
||||||
|
6 Northwest, Singapore
|
||||||
|
Ngee Ann Polytechnic
|
||||||
|
535 Clementi Road
|
||||||
|
Bukit Timah
|
||||||
|
599489
|
||||||
|
Northwest, Singapore
|
||||||
|
```
|
||||||
|
|
||||||
|
variables
|
||||||
|
|
||||||
|
- **variable `args.query`**
|
||||||
|
|
||||||
|
space-combined query given by user, comes from
|
||||||
|
[`argparse.ArgumentParser.parse_args`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args)
|
||||||
|
|
||||||
|
- **variable `squery`**
|
||||||
|
|
||||||
|
query split by comma
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ s+ 77Q4+7X Austin, Texas, USA
|
||||||
|
--------------------------
|
||||||
|
query
|
||||||
|
|
||||||
|
squery -> ['77Q4+7X', 'Austin', 'Texas', 'USA']
|
||||||
|
```
|
||||||
|
|
||||||
|
- **variables `pcode` and `locality`**
|
||||||
|
|
||||||
|
(_only shown if the query is a local code, not shown on full-length plus codes,
|
||||||
|
latlong coordinates or string queries_)
|
||||||
|
|
||||||
|
represents the plus code and locality portions of a
|
||||||
|
[shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
|
||||||
|
(_referred to as a "short/local code" in the codebase_) respectively.
|
||||||
|
|
||||||
|
- **variables `lat` and `lon`**
|
||||||
|
|
||||||
|
(_only shown if the query is a plus code_)
|
||||||
|
|
||||||
|
the latitude longitude coordinates derived from the plus code.
|
||||||
|
|
||||||
|
- **variable `location`**
|
||||||
|
|
||||||
|
the response dictionary from the reverser passed to
|
||||||
|
[`surplus.surplus()`](#surplussurplus)
|
||||||
|
|
||||||
|
- **variable `seen_names`**
|
||||||
|
|
||||||
|
a list of unique names/elements found in certain nominatim keys used in final output
|
||||||
|
lines 0-3.
|
||||||
|
|
||||||
|
- **variables for seen name checks**
|
||||||
|
|
||||||
|
the variables come from a check to reduce repeated elements found in `seen_names`.
|
||||||
|
|
||||||
|
- **variable `d`**
|
||||||
|
|
||||||
|
current element in the iteration of the final output line 4 (general regional
|
||||||
|
location) nominatim keys
|
||||||
|
|
||||||
|
- **variable `_dvmt4`**
|
||||||
|
|
||||||
|
list used in an `all()` check to see if the current nominatim key (variable `d`) can
|
||||||
|
be wholly found in any of the seen names, in the general regional location, or in
|
||||||
|
the road name.
|
||||||
|
|
||||||
|
reasoning is, if the previous lines wholly state the general regional location of the
|
||||||
|
query, there is no need to restate it.
|
||||||
|
|
||||||
|
```
|
||||||
|
# psuedocode
|
||||||
|
_dvtm4 = [
|
||||||
|
d != "",
|
||||||
|
d not in road,
|
||||||
|
d not in [output line 4 (general regional location) nominatim keys],
|
||||||
|
any(_dvcm4),
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
- **variable `_dvcm4`**
|
||||||
|
|
||||||
|
list used in an `any()` check to see if the current nominatim key (variable `d`) can
|
||||||
|
be wholly found in any of the seen names.
|
||||||
|
|
||||||
|
```python
|
||||||
|
_dvcm4 = [True if (d not in sn) else False for sn in seen_names]
|
||||||
|
```
|
||||||
|
|
||||||
|
breakdown of each output line, accompanied by their nominatim key:
|
||||||
|
|
||||||
|
```
|
||||||
|
0 name of a place
|
||||||
|
1 building name
|
||||||
|
2 highway name
|
||||||
|
3 block/house/building number, house name, road
|
||||||
|
4 general regional location
|
||||||
|
5 postal code
|
||||||
|
6 general global information
|
||||||
|
```
|
||||||
|
|
||||||
|
0. **name of a place**
|
||||||
|
|
||||||
|
(_usually important places or landmarks_)
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
The University of Queensland
|
||||||
|
Ngee Ann Polytechnic
|
||||||
|
Botanic Gardens
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
emergency, historic, military, natural, landuse, place, railway, man_made,
|
||||||
|
aerialway, boundary, amenity, aeroway, club, craft, leisure, office, mountain_pass,
|
||||||
|
shop, tourism, bridge, tunnel, waterway
|
||||||
|
```
|
||||||
|
|
||||||
|
1. **building name**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
Novena Square Office Tower A
|
||||||
|
Visitor Centre
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
building
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **highway name**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
Marina Coastal Expressway
|
||||||
|
Lornie Highway
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
highway
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **block/house/building number, house name, road**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
131 Toa Payoh Rise
|
||||||
|
535 Clementi Road
|
||||||
|
Macquarie Street
|
||||||
|
Braddell Road
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
house_number, house_name, road
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **general regional location**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
St Lucia, Greater Brisbane
|
||||||
|
The Drag, Austin
|
||||||
|
Toa Payoh Crest
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
residential, neighbourhood, allotments, quarter, city_district, district, borough,
|
||||||
|
suburb, subdivision, municipality, city, town, village
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **postal code**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
310131
|
||||||
|
78705
|
||||||
|
4066
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim key
|
||||||
|
|
||||||
|
```
|
||||||
|
postcode
|
||||||
|
```
|
||||||
|
|
||||||
|
6. **general global information**
|
||||||
|
|
||||||
|
- examples
|
||||||
|
|
||||||
|
```
|
||||||
|
Travis County, Texas, United States
|
||||||
|
Southeast, Singapore
|
||||||
|
Queensland, Australia
|
||||||
|
```
|
||||||
|
|
||||||
|
- nominatim keys
|
||||||
|
|
||||||
|
```
|
||||||
|
region, county, state, state_district, country, continent
|
||||||
|
```
|
||||||
|
|
||||||
|
## api reference
|
||||||
|
|
||||||
|
### `surplus.surplus()`
|
||||||
|
|
||||||
pluscode to shareable text conversion function
|
pluscode to shareable text conversion function
|
||||||
|
|
||||||
|
|
@ -113,7 +472,7 @@ pluscode to shareable text conversion function
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
#### `surplus.parse_query()`
|
### `surplus.parse_query()`
|
||||||
|
|
||||||
function that parses a string Plus Code, local code or latlong into a str, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) respectively
|
function that parses a string Plus Code, local code or latlong into a str, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) respectively
|
||||||
|
|
||||||
|
|
@ -122,7 +481,7 @@ function that parses a string Plus Code, local code or latlong into a str, [`sur
|
||||||
```python
|
```python
|
||||||
def parse_query(
|
def parse_query(
|
||||||
query: str, debug: bool = False
|
query: str, debug: bool = False
|
||||||
) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
|
) -> tuple[typing.Literal[True], str | Localcode | Latlong] | tuple[typing.Literal[False], str]:
|
||||||
```
|
```
|
||||||
|
|
||||||
- arguments:
|
- arguments:
|
||||||
|
|
@ -130,16 +489,14 @@ function that parses a string Plus Code, local code or latlong into a str, [`sur
|
||||||
- `query: str`
|
- `query: str`
|
||||||
string Plus Code, local code or latlong
|
string Plus Code, local code or latlong
|
||||||
|
|
||||||
- returns `tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]`
|
- returns `tuple[typing.Literal[True], str | Localcode | Latlong] | tuple[typing.Literal[False], str]`
|
||||||
|
|
||||||
- `(True, <str | surplus.Localcode | surplus.Latlong>)`
|
- `(True, <str | surplus.Localcode | surplus.Latlong>)`
|
||||||
conversion succeeded, second element is resultant Plus code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong)
|
conversion succeeded, second element is resultant Plus code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong)
|
||||||
- `(False, <str>)`
|
- `(False, <str>)`
|
||||||
conversion failed, second element is an error message string
|
conversion failed, second element is an error message string
|
||||||
|
|
||||||
---
|
### `surplus.handle_query()`
|
||||||
|
|
||||||
#### `surplus.handle_query()`
|
|
||||||
|
|
||||||
function that gets returns a [surplus.Latlong](#surpluslatlong) from a Plus Code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) object.
|
function that gets returns a [surplus.Latlong](#surpluslatlong) from a Plus Code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) object.
|
||||||
used after [`surplus.parse_query()`](#surplusparse_query).
|
used after [`surplus.parse_query()`](#surplusparse_query).
|
||||||
|
|
@ -149,7 +506,7 @@ used after [`surplus.parse_query()`](#surplusparse_query).
|
||||||
```python
|
```python
|
||||||
def handle_query(
|
def handle_query(
|
||||||
query: str | Localcode | Latlong, debug: bool = False
|
query: str | Localcode | Latlong, debug: bool = False
|
||||||
) -> tuple[Literal[True], Latlong] | tuple[Literal[False], str]:
|
) -> tuple[typing.Literal[True], Latlong] | tuple[typing.Literal[False], str]:
|
||||||
```
|
```
|
||||||
|
|
||||||
- arguments:
|
- arguments:
|
||||||
|
|
@ -162,15 +519,13 @@ used after [`surplus.parse_query()`](#surplusparse_query).
|
||||||
- [`surplus.Latlong`](#surpluslatlong)
|
- [`surplus.Latlong`](#surpluslatlong)
|
||||||
latlong
|
latlong
|
||||||
|
|
||||||
- returns `tuple[Literal[True], Latlong] | tuple[Literal[False], str]`
|
- returns `tuple[typing.Literal[True], Latlong] | tuple[typing.Literal[False], str]`
|
||||||
- `(True, <surplus.Latlong>)`
|
- `(True, <surplus.Latlong>)`
|
||||||
conversion succeeded, second element is a [`surplus.Latlong`](#surpluslatlong)
|
conversion succeeded, second element is a [`surplus.Latlong`](#surpluslatlong)
|
||||||
- `(False, <str>)`
|
- `(False, <str>)`
|
||||||
conversion failed, second element is an error message string
|
conversion failed, second element is an error message string
|
||||||
|
|
||||||
---
|
### `surplus.Localcode`
|
||||||
|
|
||||||
#### `surplus.Localcode`
|
|
||||||
|
|
||||||
`typing.NamedTuple` representing short Plus Code with locality
|
`typing.NamedTuple` representing short Plus Code with locality
|
||||||
|
|
||||||
|
|
@ -181,9 +536,7 @@ used after [`surplus.parse_query()`](#surplusparse_query).
|
||||||
- `locality: str`
|
- `locality: str`
|
||||||
e.g.: `"Singapore"`
|
e.g.: `"Singapore"`
|
||||||
|
|
||||||
---
|
#### `surplus.Localcode.full_length()`
|
||||||
|
|
||||||
##### `surplus.Localcode.full_length()`
|
|
||||||
|
|
||||||
method that calculates full-length Plus Code using locality
|
method that calculates full-length Plus Code using locality
|
||||||
|
|
||||||
|
|
@ -207,8 +560,6 @@ method that calculates full-length Plus Code using locality
|
||||||
- `(False, <str>)`
|
- `(False, <str>)`
|
||||||
conversion failed, second element is an error message string
|
conversion failed, second element is an error message string
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### `surplus.Latlong`
|
#### `surplus.Latlong`
|
||||||
|
|
||||||
`typing.NamedTuple` representing a pair of latitude and longitude coordinates
|
`typing.NamedTuple` representing a pair of latitude and longitude coordinates
|
||||||
|
|
@ -220,35 +571,8 @@ method that calculates full-length Plus Code using locality
|
||||||
- `long: float`
|
- `long: float`
|
||||||
longitudinal coordinate
|
longitudinal coordinate
|
||||||
|
|
||||||
## Developing
|
## licence
|
||||||
|
|
||||||
Prerequisites:
|
surplus is free and unencumbered software released into the public domain. for more
|
||||||
|
information, please refer to the [UNLICENCE](/UNLICENCE), <https://unlicense.org>, or the
|
||||||
- [Python >=3.10](https://www.python.org/)
|
python module docstring.
|
||||||
- [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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue