From 62d4f4c9d8904c8c466006dd8c35480989c65fb8 Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 21:05:31 -0400 Subject: [PATCH 1/6] Move default unit mappings to their own document. --- README.md | 10 ---- docs/default_unit_mappings.md | 105 ++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 10 deletions(-) create mode 100644 docs/default_unit_mappings.md diff --git a/README.md b/README.md index 15cb88f..693da59 100644 --- a/README.md +++ b/README.md @@ -172,16 +172,6 @@ multiple measurements in a message as long as each is put in its own brackets. > Lou lives about **{15km}** from me and TJ's staying at a hotel **{1.5km}** > away, so he and I are gonna meet up and drive over to Lou. -#### Supported units: - -Metric | Imperial ------- | -------- -Kilometer `km` | Mile `mi` -Meter `m` | Foot `ft or '` -Centimeter `cm` | Inch `in or "` -Kilogram `kg` | Pound `lbs` -Celsius `C or degC or °C` | Fahrenheit `F or degF or °F` - ### Time conversion Just like [unit conversion](#unit-conversion), you can also convert times diff --git a/docs/default_unit_mappings.md b/docs/default_unit_mappings.md new file mode 100644 index 0000000..b0d9c8c --- /dev/null +++ b/docs/default_unit_mappings.md @@ -0,0 +1,105 @@ +# Default unit mappings + +When no output unit is specified, Sandpiper will try to convert to another +related unit. Some units convert two ways (Celsius <-> Fahrenheit), and others +map only one way for simplicity (Kelvin -> Celsius). + +## Two-way + +The units in each row will convert to each other. + +### Length +Metric | Imperial +------ | -------- +Kilometre `km` | Mile `mi` +Metre `m` | Foot `ft or '` +Centimetre `cm` | Inch `in or "` + +### Area +Metric | Imperial +------ | -------- +Hectare `ha` | Acre `acre` + +### Speed +Metric | Imperial +------ | -------- +Kilometre per hour `kph or km/h` | Mile per hour `mph or mi/h` + +### Mass +Metric | Imperial +------ | -------- +Gram `g` | Ounce `oz` +Kilogram `kg` | Pound `lb or lbs` + +### Volume +Metric | Imperial +------ | -------- +Litre `L` | Gallon (US) `gal` +Millilitre `ml` | Cup `cup` + +### Pressure +Metric | Imperial +------ | -------- +Pascal `pascal` | Pound\[-force] per square inch `psi` + +### Temperature +Metric | Imperial +------ | -------- +Celsius `C or degC or °C` | Fahrenheit `F or degF or °F` + +### Energy +Metric | Imperial +------ | -------- +Joule `J` | Foot pound `ft_lb or foot_pound` + +### Angle +Radian | Degree +------ | -------- +Radian `rad` | Degree `deg` + + + +## One-way + +Only the units on the left will map to the unit on the right. + +### Length +From | To +---- | --- +Yard `yd` | Metre `m` + +### Speed +From | To +---- | --- +Metre per second `mps or m/s` | Kilometre per hour `kph or km/h` +Foot per second `ft/s` | Mile per hour `mph or mi/h` + +### Mass +From | To +---- | --- +Stone `stone` | Kilogram `kg` + +### Volume +From | To +---- | --- +Pint `pint` | Litre `L` +Fluid ounce `floz` | Millilitre `ml` + +### Pressure +From | To +---- | --- +Atmosphere `atm` | Pound\[-force] per square inch `psi` +Bar `bar` | Pound\[-force] force per square inch `psi` + +### Temperature +From | To +---- | --- +Kelvin `K` | Celsius `C or degC or °C` + +### Time +From | To +---- | --- +Second `s or sec` | Minute `min` +Minute `min` | Hour `h or hr` +Hour `h or hr` | Day `day` +Day `day` | Week `week` From f9dbf8d26a890f510aceae1d5056d536a058ebc9 Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 21:21:09 -0400 Subject: [PATCH 2/6] Add info and examples for explicit unit conversions and math in conversions. --- README.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 693da59..a991247 100644 --- a/README.md +++ b/README.md @@ -158,8 +158,18 @@ In servers, commands must be prefixed with the configured command prefix ### Unit conversion Convert measurements written in regular messages! Just surround a measurement -in {curly brackets} and Sandpiper will convert it for you. You can put -multiple measurements in a message as long as each is put in its own brackets. +in curly brackets -- like this: `{5 ft}` -- and Sandpiper will convert it for +you. You can put multiple measurements in a message as long as each is put in +its own brackets. + +Many measurements are converted by default without needing to specify an output +unit. Read [Default unit mappings](docs/default_unit_mappings.md) to see all +currently supported default conversions. + +You can explicitly specify an output unit like this: `{2 tonnes > lbs}`. +This opens up to you nearly any unit conversion you may need. + +Lastly, you can do math in conversions, too! `{2.3 ft + 5 in}` #### Examples @@ -172,6 +182,11 @@ multiple measurements in a message as long as each is put in its own brackets. > Lou lives about **{15km}** from me and TJ's staying at a hotel **{1.5km}** > away, so he and I are gonna meet up and drive over to Lou. +> I weigh about 9.3 stone. For you americans, that's **{9.3 stone > lbs}** + +> my two favorite songs are **{5min+27s}** and **{4min+34s}**. that's a total +> time of **{5min+27s + 4min+34s > s}** seconds + ### Time conversion Just like [unit conversion](#unit-conversion), you can also convert times From 1b2d0a9b5697ce4cdb35d9db42d2ca978fadd32c Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 22:42:09 -0400 Subject: [PATCH 3/6] Add dimensionless math example. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index a991247..5a1c3bb 100644 --- a/README.md +++ b/README.md @@ -187,6 +187,8 @@ Lastly, you can do math in conversions, too! `{2.3 ft + 5 in}` > my two favorite songs are **{5min+27s}** and **{4min+34s}**. that's a total > time of **{5min+27s + 4min+34s > s}** seconds +> hey sandpiper what's {30 * 7}? + ### Time conversion Just like [unit conversion](#unit-conversion), you can also convert times From f1f576fe36a6e26c69045e0cc9e470b98e890ea2 Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 22:48:37 -0400 Subject: [PATCH 4/6] Move config info to its own document. --- README.md | 42 +++--------------------------------------- docs/config.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 39 deletions(-) create mode 100644 docs/config.md diff --git a/README.md b/README.md index 5a1c3bb..1d4f673 100644 --- a/README.md +++ b/README.md @@ -106,49 +106,13 @@ You can enable it on the bot page of your application (https:\/\/discord.com/dev ## Config -Sandpiper can be configured with a JSON file at `./sandpiper/config.json`. +Sandpiper can be configured with a JSON file at `sandpiper/config.json`. [sandpiper/config_example.json](sandpiper/config_example.json) contains default values and can be used as a template. `bot_token` is the only required field. -### Config Fields - -#### Root - -Fields in the root JSON object. - -Key | Value ---- | ----- -`bot_token` *(string)* | Your [Discord bot's](https://discord.com/developers/docs/topics/oauth2#bots) access token - -#### Bot - -Fields in `(root).bot` which describe the bot itself. See also -the [discord.py bot documentation](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#bot) -for more info on how these fields are used. - -Key | Value ---- | ----- -`command_prefix` *(string)* | What users type to run a command -`description` *(string)* | Description of the bot (used in help messages) - -#### Logging - -Fields in `(root).logging` which describe how logging is performed. Sandpiper -uses rotating logging to write log files which rotate in specified intervals. -See also the -[TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#timedrotatingfilehandler) -for more info on how these fields are used. - -Key | Value ---- | ----- -`sandpiper_logging_level` *(string)* | Sandpiper's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'). -`discord_logging_level` *(string)* | discord.py's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'). -`output_file` *(string)* | Absolute or relative (to sandpiper module) filepath to output logs to (including filename) -`when` *(string)* | Type of time interval for rotating log files. Must be one of ('S', 'M', 'H', 'D', 'midnight') -`interval` *(integer)* | Number of specified time intervals that must elapse before rotating to a new log file -`backup_count` *(integer)* | Number of backup log files to retain (deletes oldest after limit is reached) -`format` *(string)* | Format string used when writing log messages ([format string reference](https://docs.python.org/3/library/logging.html#logrecord-attributes)) +See [Config](docs/config.md) for detailed information about setting up the +config file. ## Commands and features diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..f37eacb --- /dev/null +++ b/docs/config.md @@ -0,0 +1,45 @@ +# Config + +Sandpiper can be configured with a JSON file at `sandpiper/config.json`. +[sandpiper/config_example.json](sandpiper/config_example.json) contains +default values and can be used as a template. `bot_token` is the only required +field. + +## Config Fields + +### Root + +Fields in the root JSON object. + +Key | Value +--- | ----- +`bot_token` *(string)* | Your [Discord bot's](https://discord.com/developers/docs/topics/oauth2#bots) access token + +### Bot + +Fields in `(root).bot` which describe the bot itself. See also +the [discord.py bot documentation](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#bot) +for more info on how these fields are used. + +Key | Value +--- | ----- +`command_prefix` *(string)* | What users type to run a command +`description` *(string)* | Description of the bot (used in help messages) + +### Logging + +Fields in `(root).logging` which describe how logging is performed. Sandpiper +uses rotating logging to write log files which rotate in specified intervals. +See also the +[TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#timedrotatingfilehandler) +for more info on how these fields are used. + +Key | Value +--- | ----- +`sandpiper_logging_level` *(string)* | Sandpiper's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'). +`discord_logging_level` *(string)* | discord.py's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'). +`output_file` *(string)* | Absolute or relative (to sandpiper module) filepath to output logs to (including filename) +`when` *(string)* | Type of time interval for rotating log files. Must be one of ('S', 'M', 'H', 'D', 'midnight') +`interval` *(integer)* | Number of specified time intervals that must elapse before rotating to a new log file +`backup_count` *(integer)* | Number of backup log files to retain (deletes oldest after limit is reached) +`format` *(string)* | Format string used when writing log messages ([format string reference](https://docs.python.org/3/library/logging.html#logrecord-attributes)) From 02edd2d72c59656813869383dc3eb17eb7118850 Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 23:19:07 -0400 Subject: [PATCH 5/6] Add info and examples for the new time conversion features. --- README.md | 38 ++++++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1d4f673..6de5d51 100644 --- a/README.md +++ b/README.md @@ -156,28 +156,50 @@ Lastly, you can do math in conversions, too! `{2.3 ft + 5 in}` ### Time conversion Just like [unit conversion](#unit-conversion), you can also convert times -between timezones! Surround a time in {curly brackets} and Sandpiper will -convert it to the different timezones of users in your server. +between timezones! Surround a time in curly brackets `{5:30pm}` and Sandpiper +will convert it to the different timezones of users in your server. Times can be formatted in 12- or 24-hour time and use colon separators (HH:MM). 12-hour times can optionally include AM or PM to specify what half of the day you mean. If you don't specify, AM will be assumed. + +You can use the keywords `now`, `midnight`, and `noon` instead of a numeric time. You can put multiple times in a message as long as each is put in its own brackets. -To use this feature, you and your friends need to set your timezones with the -`timezone set` command (see the [bio commands section](#setting-your-info) -for more info). +You can explicitly specify input and output timezones very similarly to +how units are specified in unit conversion: + +Timezone specification | How to write | What it does +---------------------- | ------------ | ------------ +Input timezone | `{5:45 PM London}` | Converts 5:45 PM in London time to all timezones of users in your server +Output timezone | `{5:45 PM > Los Angeles}` | Converts 5:45 PM from your timezone to Los Angeles time +Input & output timezone | `{5:45 PM Amsterdam > Helsinki}` | Converts 5:45 PM in Amsterdam time to Helsinki time + +To use this feature without having to specify input/output timezones every time, +you and your friends need to set your timezones with the `timezone set` command +(see the [bio commands section](#setting-your-info) for more info). #### Examples -> do you guys wanna play at {9pm}? +> do you guys wanna play at **{9pm}**? -> I wish I could, but I'm busy from {14} to {17:45} +> I wish I could, but I'm busy from **{14}** to **{17:45}** -> yeah I've gotta wake up at {5} for work tomorrow, so it's an early bedtime +> yeah I've gotta wake up at **{5}** for work tomorrow, so it's an early bedtime > for me +> ugh I have a 2 hr meeting at **{noon}** tomorrow + +> my flight took off at **{7pm new york}** and landed at **{8 AM london}** + +> what time is it in dubai right now? **{now > dubai}** + +> the game's releasing at **{1 PM > new york}** for americans and +> **{1500 > london}** for europeans + +> hey alex, jaakko's getting on at **{8 pm helsinki > amsterdam}** + ### Bios Store some info about yourself to help your friends get to know you more easily! From 338efd63ebeeeb1bd38cbcee12f6821d713ae64c Mon Sep 17 00:00:00 2001 From: Hawkpath Date: Sun, 18 Apr 2021 23:32:20 -0400 Subject: [PATCH 6/6] Update unit test and coverage commands to use pytest. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6de5d51..ef1778a 100644 --- a/README.md +++ b/README.md @@ -288,13 +288,13 @@ python -m pip install -r requirements-dev.txt #### Run unit tests ```bash -python -m sandpiper.tests +python -m pytest --pyargs sandpiper ``` #### Run tests with code coverage ```bash -coverage run -m sandpiper.tests +coverage run -m pytest --pyargs sandpiper coverage html ```