diff --git a/README.md b/README.md index 6ff1184..6fce8e7 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,87 @@

- Running Calculator + Running Calculator
Running Calculator

-

A running distance and speed command line interface! Measures in metric and imperial units, as well as marathons and half-marathons.

+

Work out your running speed from a distance and a time, in whatever unit you measured it.

- - PyPI Build State - - Docker State - - PyTest State - - Pylint State - - CodeQL State - - Gitleaks State - - GitHub Version - + GitHub Version GitHub Issues - GitHub Pull Requests - - Discord Server ID - - Downloads - - GitHub Languages + License

Key Features • - Download • - How To Use • + Installation • + Usage • + Documentation • Support • Contributing • - Changelog • - Credits & Contributors + Credits • + License

- -![screenshot](https://raw.githubusercontent.com/willtheorangeguy/Running-Calculator/refs/heads/main/docs/images/welcome.png) + +
+ Running Calculator +
## Key Features -* Easily input distance of a run. -* Input distance can be in marathons, half-marathons, miles, feet, kilometers and meters. -* Easily input run time. -* Displays speeds in meters per second and kilometers per hour. -* Cross platform. - -## Download - -You can **[download](https://github.com/willtheorangeguy/Running-Calculator/releases/latest) the source code** to run the script from the command line on Windows, macOS and Linux. **This will require [Python](https://www.python.org/downloads/).** - -You can **[download](https://github.com/willtheorangeguy/Running-Calculator/releases/latest) the latest executable version** of Running Calculator for Windows. **This does not require Python.** +- Enter a distance in **marathons, half marathons, miles, feet, kilometres, or metres**. +- Enter a time in hours, minutes, and seconds. +- Get speed in metres per second and kilometres per hour. +- Loops, so you can do several runs in one sitting. +- Pure standard library; runs anywhere Python does. -## How To Use +Results are always metric, whatever you entered. -To run the application, you can use [Git and the Python Interpreter](https://github.com/willtheorangeguy/Running-Calculator/main/README.md#git), which allows you to clone and run the application, [`pip`](https://github.com/willtheorangeguy/Running-Calculator/main/README.md#pip) to create a command line application, or [Docker](https://github.com/willtheorangeguy/Running-Calculator/main/README.md#docker) to create a container of the application. - -### Git - -To clone and run this application, you'll need [Git](https://git-scm.com/downloads) and [Python](https://www.python.org/downloads/) installed on your computer. If you would rather not use Git, you can just download the script from GitHub above. From your command line: +## Installation ```bash -# Clone this repository -$ git clone https://github.com/willtheorangeguy/Running-Calculator - -# Go into the repository -$ cd Running-Calculator - -# Run the CLI -$ python main.py +git clone https://github.com/willtheorangeguy/Running-Calculator +cd Running-Calculator +python main.py ``` -### `pip` +Also on PyPI and as a Docker image — see [`docs/installation.md`](docs/installation.md). -You can install the program from the [Python Package Index](https://pypi.org/project/Running-Calculator/) through `pip`. +## Usage -```bash -# Install via pip -$ pip install running-calculator - -# Run the CLI -$ running-calculator +``` +What unit will you be inputting? miles +How far did you run? 3.1 +How many hours did it take you? (if < 1, enter 0) 0 +How many minutes did it take you? (if < 1, enter 0) 27 +How many seconds did it take you? 14 ``` -### Docker +Type `license` for the licence notice, or `quit` to leave. -You can pull the [Docker](https://www.docker.com/) image from GitHub Packages. From your command line: +> **Do not enter zero for all three time fields** — it divides by zero and exits with a traceback. See [`docs/internal/known-issues.md`](docs/internal/known-issues.md). -```bash -# Pull image -$ docker pull ghcr.io/willtheorangeguy/running-calculator:main +## Documentation -# Run container -$ docker run -i -t ghcr.io/willtheorangeguy/running-calculator:main python main.py -``` +Full documentation lives in [`docs/`](docs/README.md): +[Quickstart](docs/quickstart.md) · [Installation](docs/installation.md) · [Units](docs/units.md) · [Architecture](docs/architecture.md) · [Development](docs/development.md) · [FAQ](docs/faq.md) · [Troubleshooting](docs/troubleshooting.md) · [Roadmap](docs/roadmap.md) ## Support -**The following units are available (can be generated by using the `help` command):** - -```text -Marathons 42195m -Half Marathons 21907.5m -Miles 1069.3m -Feet 0.38m -Kilometers 1000m -Meters 1m -license View the license file. -exit Exit the program. -quit Exit the program. -``` - -More documentation is available in the **[Documentation](https://github.com/willtheorangeguy/Running-Calculator/tree/main/docs)** and on the **[Wiki](https://github.com/willtheorangeguy/Running-Calculator/wiki)**. If more support is required, please open a **[GitHub Discussion](https://github.com/willtheorangeguy/Running-Calculator/discussions/new)** or join our **[Discord](https://discord.gg/2eBHwHaPWp)**. +Open a [GitHub Discussion](https://github.com/willtheorangeguy/Running-Calculator/discussions) or file an [issue](https://github.com/willtheorangeguy/Running-Calculator/issues/new/choose). ## Contributing Please contribute using [GitHub Flow](https://guides.github.com/introduction/flow). Create a branch, add commits, and [open a pull request](https://github.com/willtheorangeguy/Running-Calculator/compare). -Please read [`CONTRIBUTING`](https://github.com/willtheorangeguy/.github/blob/main/CONTRIBUTING.md) for details on our [`CODE OF CONDUCT`](https://github.com/willtheorangeguy/.github/blob/main/CODE_OF_CONDUCT.md), and the process for submitting pull requests to us. - -## Changelog - -See the [`CHANGELOG`](CHANGELOG.md) file for details. +See the org-wide [Contributing Guide](https://github.com/willtheorangeguy/.github/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/willtheorangeguy/.github/blob/main/CODE_OF_CONDUCT.md). ## Credits @@ -162,10 +109,8 @@ This software uses the following open source packages, projects, services or web -## Contributors - -* [@willtheorangeguy](https://github.com/willtheorangeguy) +Sponsor [@willtheorangeguy](https://github.com/willtheorangeguy) on [PayPal](https://paypal.me/wvdg44?country.x=CA&locale.x=en_US). ## License -This project is licensed under the [MIT License](https://mit-license.org/) - see the [`LICENSE`](LICENSE.md) file for details. +MIT — see [`LICENSE.md`](LICENSE.md). diff --git a/docs/README.md b/docs/README.md index 548515f..47049c6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,53 @@ -# Running Calculator Documentation +# Running Calculator — Documentation -This folder includes all of the docs for Running Calculator. More can be found on the [wiki](https://github.com/willtheorangeguy/Running-Calculator/wiki). +Converts a distance and a time into a speed, from the command line. -```text -├── docs -| ├── images -| ├── USAGE.md -| ├── UNITS.md -└── README.md ``` +Running-Calculator/ +├── main.py the whole program: prompts, conversion, output +└── docs/ this documentation +``` + +## Pages + +- [Quickstart](./quickstart.md) — one run, start to finish +- [Installation](./installation.md) — source, PyPI, Docker +- [Units](./units.md) — what each unit converts to +- [Architecture](./architecture.md) — the three functions +- [Development](./development.md) — tests and conventions +- [FAQ](./faq.md) — metric output, accepted units, the loop +- [Troubleshooting](./troubleshooting.md) — the crash, and unrecognised units +- [Roadmap](./roadmap.md) — direction and non-goals +- [Known issues](./internal/known-issues.md) — recorded defects + +## Two things to know + +**Zero time crashes it.** The speed is `distance / time` with no guard, so entering 0 hours, 0 +minutes, and 0 seconds exits with a `ZeroDivisionError` traceback. The prompts invite zeros — +"(if < 1, enter 0)" — which makes it easy to hit while exploring. + +**The in-program unit list has wrong numbers.** Typing an unrecognised unit prints a reference +table, and three of its six values are wrong. The conversions the program *uses* are correct, so +your results are right; the reference is not. See [Units](./units.md) for the correct figures. + +Both in [`internal/known-issues.md`](./internal/known-issues.md). + +## What it does + +1. Asks which unit you are entering. +2. Asks the distance, then hours, minutes, and seconds. +3. Converts everything to metres and seconds. +4. Prints the distance (in metres or kilometres) and the speed in m/s and km/h. +5. Loops for another run. + +Output is always metric, whatever you entered — the program says so on startup. + +## Extra commands + +At the unit prompt: + +| Input | Does | +|---|---| +| `license` | Prints the licence notice | +| `quit` or `exit` | Leaves | +| Anything unrecognised | Prints the unit list and asks again | diff --git a/docs/UNITS.md b/docs/UNITS.md deleted file mode 100644 index b9ff162..0000000 --- a/docs/UNITS.md +++ /dev/null @@ -1,63 +0,0 @@ -# Running Calculator Commands - -**The following units and commands are available in Running Calculator:** - -```text -Marathons 42195m -Half Marathons 21907.5m -Miles 1069.3m -Feet 0.38m -Kilometers 1000m -Meters 1m -license View the license file. -exit Exit the program. -quit Exit the program. -``` - -## `Marathons` - -1 marathon is 42,195 meters. - -## `Half Marathons` - -1 half marathon is 21,907.5 meters. - -## `Miles` - -1 mile is 1069.3 meters. - -## `Feet` - -1 foot is 0.38 meters. - -## `Kilometers` - -1 half marathon is 1000 meters. - -## `Meters` - -1 meter is 1 meter. - -## `license` - -Shows the GNU GPL v3 license text. The full license can be accessed in the `LICENSE.md` file. - -## `help` - -Prints a list of each of the available commands. Example: - -```text -Please try again. Options are: -Marathons 42195m -Half Marathons 21907.5m -Miles 1069.3m -Feet 0.38m -Kilometers 1000m -Meters 1m -exit Exit the program. -quit Exit the program. -``` - -## `exit` or `quit` - -Exits the program. Useful for when calculations are completed. diff --git a/docs/USAGE.md b/docs/USAGE.md deleted file mode 100644 index 14ee8d9..0000000 --- a/docs/USAGE.md +++ /dev/null @@ -1,33 +0,0 @@ -# Running Calculator Usage - -To install Running Calculator, you can use an executable package (Windows), run the scripts through Python (Windows, macOS, Linux), install from the [Python Package Index](https://pypi.org/), or run a [Docker](https://www.docker.com/) container from [GitHub Packages](https://github.com/willtheorangeguy/Running-Calculator/pkgs/container/running-calculator). - -## Executable Package - -1. To run the executable package, download the latest `.zip` file from [GitHub Releases](https://github.com/willtheorangeguy/Running-Calculator/releases/latest) page. -2. Extract the `.zip` file using a program like [7-Zip](https://www.7-zip.org/). -3. _(Optional) Move the files to `C:\Program Files` and create a shortcut._ -4. Double click on `main.exe`. -5. Enjoy the program! - -## Python Script - -1. To run the Python script, download the latest source code release from [GitHub Releases](https://github.com/willtheorangeguy/Running-Calculator/releases/latest) page. -2. Download and install [Python](https://www.python.org/downloads/). -3. Extract the source code files using a program like [7-Zip](https://www.7-zip.org/). -4. Double click on `main.py`, or right-click and open with IDLE and press `F5`. -5. Enjoy the program! - -## Python Package Index (`pip`) - -1. Download and install [Python](https://www.python.org/downloads/). -2. Open a terminal and run the command: `pip install running-calculator`. -3. Start the program by running the command: `running-calculator`. -5. Enjoy the program! - -## Docker Container - -1. Download and install [Docker](https://www.docker.com/products/docker-desktop/). -2. Open a terminal and pull the container: `docker pull ghcr.io/willtheorangeguy/running-calculator:main`. -3. Start the container: `docker run -i -t ghcr.io/willtheorangeguy/running-calculator:main python main.py`. -4. Enjoy the program! diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..c2e148c --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,70 @@ +# Running Calculator — Architecture + +One file, 203 lines, three functions. + +``` +main() + ├── unit prompt → a chain of elif comparisons setting `unit` + ├── time prompts → float/int, wrapped in try/except ValueError + ├── conversion → everything to metres and seconds + ├── calculate_distance → metres or kilometres for display + └── display_result → the output +``` + +## `main()` + +Two nested loops: an outer `while run` for successive runs, and inner loops for the unit and the +time entry. Both inner flags are reset at the bottom so the next run starts clean. + +The unit prompt is a chain of `elif` comparisons against lowercased input, accepting singular and +plural. `license`, `quit`, and `exit` are handled in the same chain — which is why they are only +available at that prompt and not during time entry. + +## Input validation + +```python +try: + time_run = False + length = float(input("How far did you run? ")) + hours = int(input(...)) + ... +except ValueError: + print("Values must be in numerical form, and only seconds can be a decimal!") + time_run = True +``` + +Catching `ValueError` and re-prompting is right, and the message correctly explains that only +seconds may be fractional — `hours` and `mins` are parsed with `int`. + +What is not guarded is a **total time of zero**, which reaches `distance / time` and raises +`ZeroDivisionError`. Negative values are also accepted, producing a negative speed. See +[`internal/known-issues.md`](./internal/known-issues.md). + +## Conversion + +Constants at the top of `main()`: + +```python +FT = 3.281 +MILES = 1609.344 +HALF_MARATHON = 21097.5 +MARATHON = 42195 +``` + +Each unit multiplies (or, for feet, divides) into metres. These values are correct — unlike the +reference table printed on unrecognised input, which disagrees with three of them. See +[Units](./units.md). + +## `calculate_distance(distance, unit)` + +Returns metres below 1,000 and kilometres above, overwriting the `unit` argument it was passed. +Purely for display; the speed is computed from the metre value before this is called. + +## `display_result(...)` + +Prints the distance and both speeds, rounded to two places. + +## What is absent + +No pace (minutes per kilometre or mile), no imperial output, no history, no persistence, and no +argument parsing — the program is interactive only. See [Roadmap](./roadmap.md). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..2588505 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,54 @@ +# Running Calculator — Development + +## Setup + +```bash +git clone https://github.com/willtheorangeguy/Running-Calculator +cd Running-Calculator +pip install -r requirements.txt +python main.py +``` + +No runtime dependencies. + +## Tests + +```bash +pytest +``` + +`tests/` covers the calculation and display helpers. `calculate_distance` and `display_result` +are separate functions precisely so they can be tested without driving the prompts — keep that +split. + +`main()` itself is one long interactive loop and is not directly testable. Anything new worth +asserting should go in a function outside it. + +## Where the known issues live + +Both are in `main()`: + +- **`metersps = distance / time`** with no zero guard. +- **The unit list printed on unrecognised input**, whose half-marathon, mile, and foot values + disagree with the constants a few lines below. + +The second is the more interesting one to fix properly: the constants and the printed table are +two hand-maintained copies of the same facts, which is why they drifted. Printing the table from +the constants would make it impossible. + +## Conventions + +- **Module docstring and copyright header** on every file. +- **Pylint**, with per-file disables at the top. +- Standard library only. +- **American unit spellings** in the input matching. + +## The licence notice + +The in-program `license` command prints `Copyright (C) 2022-2023`, while the module header says +2022-2026. Worth reading from one place if either is ever updated. + +## Recording defects + +Bugs found while working here go in [`internal/known-issues.md`](./internal/known-issues.md) +rather than being fixed in passing, unless fixing them is the job you are on. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..6a4043a --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,52 @@ +# Running Calculator — FAQ + +### It crashed when I entered zero for the time. + +`ZeroDivisionError` — the speed is `distance / time` with no guard against a total of zero. The +prompts suggest entering `0` for hours and minutes, so it is easy to reach by entering `0` for +all three while trying it out. + +Recorded in [`internal/known-issues.md`](./internal/known-issues.md). + +### The unit list shows different numbers from the documentation. + +The documentation is right. Three rows of the in-program list are wrong — half marathons, miles, +and feet — while the constants the program actually calculates with are correct. + +So your results are fine; the printed reference is not. See [Units](./units.md). + +### Why is the output always metric? + +By design, and the program says so on startup. Distances come back in metres or kilometres, and +speeds in m/s and km/h, whatever you entered. + +### Can I get my pace instead of my speed? + +No — minutes per kilometre or mile is not calculated. See [Roadmap](./roadmap.md). + +### `kilometres` is not recognised. + +Only American spellings. Singular and plural both work, and case does not matter. + +### Can I enter a negative distance or time? + +It will accept them and produce a negative speed. There is no range checking. + +### Does it remember previous runs? + +No. Nothing is written to disk. The loop lets you do several in one sitting, and they are gone +when you exit. + +### How accurate are the conversions? + +The marathon and half-marathon figures are exact by definition, and the mile is the international +mile. The foot is derived as `1 / 3.281`, which gives 0.30479 rather than the defined 0.3048 — a +difference of about 3 mm per kilometre, invisible at running distances. + +### How do I quit? + +Type `quit` or `exit` at the unit prompt. They are not accepted during the time prompts. + +### What does `license` do? + +Prints the licence notice. Note it says 2022-2023 while the file header says 2022-2026. diff --git a/docs/images/help.png b/docs/images/help.png deleted file mode 100644 index 64177f3..0000000 Binary files a/docs/images/help.png and /dev/null differ diff --git a/docs/images/logo.png b/docs/images/logo.png deleted file mode 100644 index 87368bd..0000000 Binary files a/docs/images/logo.png and /dev/null differ diff --git a/docs/images/usage.png b/docs/images/usage.png deleted file mode 100644 index b04c3d3..0000000 Binary files a/docs/images/usage.png and /dev/null differ diff --git a/docs/images/welcome.png b/docs/images/welcome.png deleted file mode 100644 index a89abd9..0000000 Binary files a/docs/images/welcome.png and /dev/null differ diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..c1672b9 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,45 @@ +# Running Calculator — Installation + +## Requirements + +Python 3.x. No dependencies. + +## From source + +```bash +git clone https://github.com/willtheorangeguy/Running-Calculator +cd Running-Calculator +python main.py +``` + +## From PyPI + +```bash +pip install running-calculator +running-calculator +``` + +## Docker + +```bash +docker pull ghcr.io/willtheorangeguy/running-calculator:main +docker run -i -t ghcr.io/willtheorangeguy/running-calculator:main +``` + +Interactive mode matters — the program is a series of prompts, so `-i -t` is required. + +## Verify + +```bash +python main.py +``` + +You should get the ASCII runner, the banner, and the unit prompt. Type `quit` to leave. + +## Uninstall + +```bash +pip uninstall running-calculator +``` + +Nothing is written to disk — no config, no history, no saved runs. diff --git a/docs/internal/known-issues.md b/docs/internal/known-issues.md new file mode 100644 index 0000000..b628dd5 --- /dev/null +++ b/docs/internal/known-issues.md @@ -0,0 +1,65 @@ +# Known Issues — Running-Calculator + +Concrete defects and gaps found while writing this repository's documentation in +August 2026. **Nothing here was changed** — each one needs a code, configuration, or +licensing decision rather than a documentation one. + +Ordered by severity. See [`docs/roadmap.md`](../roadmap.md) for the narrative version, +which also covers deliberate non-goals. + + +**3 open:** 2 medium, 1 low. + +## 1. A total time of zero divides by zero and exits with a traceback + +**Severity:** Medium +**Where:** `main.py` -> `main`, `metersps = distance / time` + +**What:** `time = (hours * 3600) + (mins * 60) + secs`, then `metersps = distance / time` with no check that `time` is non-zero. Entering `0` for hours, minutes, and seconds raises `ZeroDivisionError: float division by zero` and the program exits with a traceback. Verified by running it. The `try/except ValueError` around the four inputs catches non-numeric entry but not this. + +**Why it matters:** The prompts actively invite the input that causes it: two of them read 'if < 1, enter 0'. Someone trying the program out, or checking what it does with a trivial case, will enter zeros and get a Python traceback rather than a message -- and because the crash exits rather than re-prompting, the whole session is lost including any earlier runs they had done in the loop. Every other bad input in this program is handled politely, which makes the one that is not more surprising. + +**Suggested fix:** Guard before dividing: if `time <= 0`, print a sentence and re-prompt through the existing `time_run` loop, which is already there for the `ValueError` path. Negative values deserve the same check -- they are currently accepted and produce a negative speed. + +## 2. Three of the six conversions in the in-program unit list are wrong + +**Severity:** Medium +**Where:** `main.py` -> the `else` branch of the unit prompt + +**What:** Entering an unrecognised unit prints a reference table. Three rows disagree with the constants the program calculates with: + + printed constant correct + Half Marathons 21907.5m HALF_MARATHON = 21097.5 21097.5 + Miles 1069.3m MILES = 1609.344 1609.344 + Feet 0.38m 1 / FT (3.281) 0.3048 + +The half-marathon and mile figures are digit transpositions of the correct values; the foot figure is simply wrong. Marathons, kilometres, and metres are right. + +**Why it matters:** The calculations are unaffected -- they use the constants -- so results are correct and only the reference is wrong, which is why this is Medium rather than High. But the table is printed precisely when a user is confused about units, so it is consulted at the moment they are least able to spot an error, and two of the three wrong values are transpositions that look plausible. Someone using it to sanity-check a distance elsewhere gets a mile 540 m short. + +The root cause is that the constants and the printed table are two hand-maintained copies of the same six facts, twenty lines apart. + +**Suggested fix:** Print the table from the constants rather than from literals -- a dict of unit name to metres, used by both the conversion branch and the help output. That removes the possibility of drift rather than correcting three instances of it. + +## 3. The in-program licence notice is dated differently from the file header + +**Severity:** Low +**Where:** `main.py` -> the `license` command; module docstring + +**What:** The `license` command prints `Running Calculator Copyright (C) 2022-2023 @willtheorangeguy`. The module docstring at the top of the same file reads `Copyright (C) 2022-2026 willtheorangeguy`. + +**Why it matters:** Small, and it is the one output whose job is stating the copyright accurately -- a user who types `license` is asking that exact question and gets an answer three years stale. The same pattern appears in `LEGO-Block-Creator` and `ProgramVer` in this sweep, which suggests the in-program notices across these projects were written once and never revisited. + +**Suggested fix:** Derive both from one place, or at minimum update the command's string. Reading the year from `datetime` would stop it recurring. + + +--- + +## Also, across every repository + +**`.bandit` is present on disk but untracked in git.** Verified in PyWorkout, treklogger, +skyscanner-cli, booking-cli, piggy, and aibot — the config file exists locally in each but +`git ls-files` does not know about it, so none of it reached GitHub. + +The August 2026 security sweep therefore looks complete locally and landed nowhere. Worth +checking across all 44 repositories it covered. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..5cd10c3 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,62 @@ +# Running Calculator — Quickstart + +## Run it + +```bash +git clone https://github.com/willtheorangeguy/Running-Calculator +cd Running-Calculator +python main.py +``` + +No dependencies. + +## A run, start to finish + +``` +What unit will you be inputting? miles +You are now entering in miles! + +How far did you run? 3.1 +How many hours did it take you? (if < 1, enter 0) 0 +How many minutes did it take you? (if < 1, enter 0) 27 +How many seconds did it take you? 14 + +You traveled 4.99 kilometers. +Your speed was 3.06 meters per second or 11.01 kilometers per hour. +``` + +Then it asks again, so you can do several runs without restarting. + +## Units + +`marathons`, `half marathons`, `miles`, `feet`, `kilometers`, `meters` — singular or plural, +case-insensitive, American spellings only. Full table in [Units](./units.md). + +Anything else prints the unit list and asks again. Note three of the numbers in that printed list +are wrong; [Units](./units.md) has the correct ones. + +## Do not enter zero for the whole time + +``` +How many hours did it take you? 0 +How many minutes did it take you? 0 +How many seconds did it take you? 0 +``` + +crashes with `ZeroDivisionError` — the speed is `distance / time` with nothing guarding a zero +total. The prompts explicitly suggest entering `0`, so it is easy to do while trying the program +out. Recorded in [`internal/known-issues.md`](./internal/known-issues.md). + +## Other commands + +At the unit prompt: + +| Input | Does | +|---|---| +| `license` | Prints the licence notice | +| `quit`, `exit` | Leaves | + +## Output is metric + +Whatever you enter, results come back in metres or kilometres, and speeds in m/s and km/h. The +program says so on startup. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..762a2c4 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,50 @@ +# Running Calculator — Roadmap + +Direction, not a schedule. Defects are in +[`internal/known-issues.md`](./internal/known-issues.md). + +## Where it is + +Converts six distance units and a time into speed in m/s and km/h, loops for successive runs, and +validates numeric input. Two helper functions are separated out and tested. + +## Considered + +**Guarding zero time.** The one crash in the program, and the prompts invite the input that +causes it. + +**Printing the unit table from the constants.** The table and the constants are two hand-kept +copies of the same six facts, and three have drifted. Deriving one from the other makes the class +of bug impossible rather than fixing three instances of it. + +**Pace as well as speed.** Minutes per kilometre or mile is how runners actually talk about this, +and it is the same arithmetic inverted. + +**Imperial output.** The startup message apologises for metric-only, which suggests it was always +meant to be optional. + +**Range checking.** Negative distances and times are accepted and produce negative speeds. + +**Command-line arguments.** Interactive-only means it cannot be scripted or piped. + +## Non-goals + +**GPS, watches, or file import.** Reading a track file or a watch export is a different program. +This takes two numbers. + +**Storing runs.** A training log needs somewhere to keep data and something to show over time. +This answers one question and exits. + +**Predicting race times.** Well served elsewhere, and a prediction presented next to a measurement +invites confusing the two. + +**Guessing the unit.** The program takes your word for what you entered rather than inferring from +magnitude. A 5 that means kilometres and a 5 that means miles are both plausible, and guessing +wrong would be silent. + +## Contributing + +Issues and pull requests welcome — see the +[Contributing Guide](https://github.com/willtheorangeguy/.github/blob/main/CONTRIBUTING.md). + +The zero-time guard is two lines and removes the only way to crash it. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..c92c75b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,57 @@ +# Running Calculator — Troubleshooting + +## `ZeroDivisionError: float division by zero` + +You entered zero for hours, minutes, and seconds. The speed calculation has no guard for a total +time of zero. + +Enter the real time. If you genuinely want to check the behaviour, one second is enough. + +Recorded in [`internal/known-issues.md`](./internal/known-issues.md). + +## "Please try again. Options are:" when I typed a real unit + +Only these are recognised, in American spelling: + +`marathons`, `half marathons`, `miles`, `feet`, `kilometers`, `meters` — singular or plural. + +The British spellings are not, and neither are abbreviations like `km`, `mi`, or `ft`. + +## The unit list numbers look wrong + +They are, for three of the six rows. [Units](./units.md) has the correct figures. Your +calculations are unaffected — the program uses its constants, not the printed list. + +## "Values must be in numerical form" + +Hours and minutes are parsed as integers; only seconds may have a decimal point. `1.5` hours is +rejected — enter `1` hour and `30` minutes. + +All four values are re-prompted after this error, not just the bad one. + +## `quit` does not work + +It is only recognised at the unit prompt. Once you are entering distance and time, finish the +entry or interrupt with Ctrl+C. + +## The speed looks far too high or low + +Check the unit you selected. Entering a marathon distance while in `meters` mode gives a very +different answer from `marathons` mode — the program takes your word for the unit. + +## Nothing happens in Docker + +The program is interactive, so the container needs a TTY: + +```bash +docker run -i -t ghcr.io/willtheorangeguy/running-calculator:main +``` + +## The ASCII art is mangled + +A terminal narrower than the banner, or one without UTF-8. Cosmetic. + +## Still stuck + +[Open an issue](https://github.com/willtheorangeguy/Running-Calculator/issues/new/choose) with +what you entered and what came back. diff --git a/docs/units.md b/docs/units.md new file mode 100644 index 0000000..920d1d5 --- /dev/null +++ b/docs/units.md @@ -0,0 +1,63 @@ +# Running Calculator — Units + +## Accepted at the unit prompt + +Singular and plural both work, and matching is case-insensitive. + +| Input | Also accepted | +|---|---| +| `marathons` | `marathon` | +| `half marathons` | `half marathon` | +| `miles` | `mile` | +| `feet` | `foot` | +| `kilometers` | `kilometer` | +| `meters` | `meter` | + +American spellings only — `kilometres` and `metres` are not recognised. + +## The conversions the program uses + +These are the constants in `main.py`, and they are correct: + +| Unit | Metres | +|---|---| +| Marathon | 42,195 | +| Half marathon | 21,097.5 | +| Mile | 1,609.344 | +| Foot | 0.3048 (as `1 / 3.281`) | +| Kilometre | 1,000 | +| Metre | 1 | + +A marathon is 42.195 km by definition, and a half marathon exactly half of it. The mile figure is +the international mile. The foot is derived by dividing by 3.281 feet-per-metre, which gives +0.30479 — close enough to the defined 0.3048 that it will not show at running distances. + +## The list the program prints is wrong + +Entering an unrecognised unit prints a reference table, and three of its six rows disagree with +the constants above: + +| Row | Printed | Correct | +|---|---|---| +| Half Marathons | 21907.5m | **21097.5m** — digits transposed | +| Miles | 1069.3m | **1609.344m** — digits transposed | +| Feet | 0.38m | **0.3048m** | +| Marathons | 42195m | Correct | +| Kilometers | 1000m | Correct | +| Meters | 1m | Correct | + +**Your results are not affected** — the calculation uses the constants, not the printed table. But +anyone reading those numbers as a reference gets three wrong ones, and the two transpositions are +the kind that look plausible. + +Recorded in [`internal/known-issues.md`](./internal/known-issues.md). + +## Output units + +Always metric: + +- Distance in **metres** below 1,000, **kilometres** above. +- Speed in **metres per second** and **kilometres per hour**. + +There is no imperial output, and no pace (minutes per kilometre or mile) — see +[Roadmap](./roadmap.md).