diff --git a/README.md b/README.md index 5a7dbdd..50d8123 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,194 @@ -# Weather Data (Day 25) - -Reading CSV weather data in Python, first with the built-in `csv` library and then -with `pandas`. It is the day-25 assignment of Udemy's *100 Days of Code: The -Complete Python Pro Bootcamp*. The lectures read the weather of one week from -`weather_data.csv`, collect the temperatures as whole numbers, and then show how -`pandas` does the same in one line: a table is a `DataFrame` and a column of it is -a `Series`. They convert both to a dictionary and a list, compute the average and -the maximum temperature, select rows by a condition (the row of Monday, the row of -the hottest day, Monday's temperature in Fahrenheit), create a `DataFrame` from a -dictionary, and export it to a CSV file. - -The `csv` part has no runtime dependencies; `pandas` is an optional extra. The code -keeps the names of the lectures (`data`, `temperatures`, `temp_list`, `data_dict`, -`average_temp`, `monday`, `to_dict`, `to_list`, `mean`, `max`, `to_csv`) so that you -can compare it with your own solution. - -> **Status:** in progress. The project foundation (configuration, constants, -> documentation settings and continuous integration) is in place; the readers and -> the analysis follow in the next milestones, see `docs/project-plan.md`. - -## Requirements - -- Python 3.13 or newer. -- `git`, to clone the repository. -- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. -- No runtime dependencies. `pandas` (the optional extra `pandas`) is needed for the - second half of the lectures and is installed by the `dev` extra, together with - the development tools (`pytest`, `ruff`, `mypy`). - -## Set up - -Clone the repository, then create a local virtual environment `.venv` in its -root, upgrade `pip` and install the project with its development tools. The -`.venv` folder is ignored by git. - -```bash -git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/025-weather.git -cd 025-weather -``` - -### Windows powershell - -```powershell -python -m venv .venv -.\.venv\Scripts\Activate.ps1 -python -m pip install --upgrade pip -python -m pip install -e ".[dev]" -``` - -If PowerShell refuses to run the activation script, allow scripts for this -window only with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned` -and activate again. - -### Linux debian - -Debian 13 or newer ships Python 3.13. On older releases install Python 3.13 -separately. - -```bash -sudo apt install python3 python3-venv -python3 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install -e ".[dev]" -``` - -### MacOS - -```bash -brew install python@3.13 -python3.13 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install -e ".[dev]" -``` - -To install only what the `csv` part needs, leave out the extras: -`python -m pip install -e .`. To add `pandas` without the development tools use -`python -m pip install -e ".[pandas]"`. - -## Run - -With the virtual environment active, the program that prints the results of the -lectures is added in a later milestone (`python -m weather`); until then the -package can be imported: - -```bash -python -c "from weather import constants; print(constants.DATA_FILE)" -``` - -## Run the tests - -The tests write only into temporary folders. - -```bash -pytest -``` - -The same checks that continuous integration runs: - -```bash -python -m pytest -python -m ruff check src tests -python -m ruff format --check src tests -python -m mypy -``` - -## Continuous integration - -`.gitea/workflows/ci.yml` runs on Gitea Actions on every push and on every pull -request. It sets up Python 3.13, upgrades `pip`, installs `.[dev]`, then runs -`pytest`, `ruff` (lint and format check) and `mypy`. It does not build the source -documentation: run `doxygen Doxyfile` yourself, as the next section shows. - -The workflow lives in `.gitea/workflows` and not in `.github/workflows`, so -GitHub does not run it and pushing to a GitHub mirror needs no workflow -permission. - -## Build the source documentation - -The source is documented with Doxygen comments and the `Doxyfile` in the root. -Install Doxygen (`winget install DimitriVanHeesch.Doxygen` on Windows, -`sudo apt install doxygen` on Debian, `brew install doxygen` on macOS), then: - -```bash -doxygen Doxyfile -``` - -The HTML is written to `build/doxygen/index.html`. A warning fails the build. - -## Project layout - -```text -. -├── .gitea/workflows/ci.yml continuous integration (Gitea Actions) -├── docs/ business case, plan, milestones, reviews -├── src/weather/ the package -│ ├── __init__.py -│ └── constants.py every constant of the lectures -├── tests/ pytest tests (conftest.py runs every test in a -│ temporary folder) -├── Doxyfile source documentation settings -├── LICENSE -├── pyproject.toml project configuration -└── README.md -``` - -## License - -GNU Affero General Public License v3.0 only. See [LICENSE](LICENSE). +# Weather Data (Day 25) + +Reading CSV weather data in Python, first with the built-in `csv` library and then +with `pandas`. It is the day-25 assignment of Udemy's *100 Days of Code: The +Complete Python Pro Bootcamp*. The lectures read the weather of one week from +`weather_data.csv`, collect the temperatures as whole numbers, and then show how +`pandas` does the same in one line: a table is a `DataFrame` and a column of it is +a `Series`. They convert both to a dictionary and a list, compute the average and +the maximum temperature, select rows by a condition (the row of Monday, the row of +the hottest day, Monday's temperature in Fahrenheit), create a `DataFrame` from a +dictionary, and export it to a CSV file. + +The `csv` part has no runtime dependencies; `pandas` is an optional extra. The code +keeps the names of the lectures (`data`, `temperatures`, `temp_list`, `data_dict`, +`average_temp`, `monday`, `to_dict`, `to_list`, `mean`, `max`, `to_csv`) so that you +can compare it with your own solution. + +![The program running in a terminal: the rows and temperatures read with the csv library, then the data frame, the dictionary, the list, the average 17.428571428571427, the maximum 24, the row of Monday, the hottest row Sunday, Monday in Fahrenheit 53.6 and the scores frame](docs/images/weather-run.png) + +*`python -m weather` in a terminal: the csv part first, then the pandas part.* + +> **Status:** finished. The `csv` reader, the `pandas` analysis, the creation and +> export of a `DataFrame` and the program that prints the results are done. A short +> description in English, Danish and Bahasa Melayu is on the wiki of the repository +> (the pages are in `wiki/`). + +## Requirements + +- Python 3.13 or newer. +- `git`, to clone the repository. +- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. +- No runtime dependencies. `pandas` (the optional extra `pandas`) is needed for the + second half of the lectures and is installed by the `dev` extra, together with + the development tools (`pytest`, `ruff`, `mypy`). + +## Set up + +Clone the repository, then create a local virtual environment `.venv` in its +root, upgrade `pip` and install the project with its development tools. The +`.venv` folder is ignored by git. + +```bash +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/025-weather.git +cd 025-weather +``` + +### Windows powershell + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, allow scripts for this +window only with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned` +and activate again. + +### Linux debian + +Debian 13 or newer ships Python 3.13. On older releases install Python 3.13 +separately. + +```bash +sudo apt install python3 python3-venv +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### MacOS + +```bash +brew install python@3.13 +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +To install only what the `csv` part needs, leave out the extras: +`python -m pip install -e .`. To add `pandas` without the development tools use +`python -m pip install -e ".[pandas]"`. + +## Run + +With the virtual environment active, print the results of the lectures: + +```bash +python -m weather +``` + +The program prints, in the order of the lectures: + +1. the rows of `weather_data.csv` and the temperatures as whole numbers, read with + the `csv` library (no `pandas` needed); +2. the same file read with `pandas` as a `DataFrame`, converted to a dictionary and + a list; +3. the average temperature, computed by hand and with `mean`, and the maximum; +4. the row of Monday, the row of the hottest day, and Monday in Fahrenheit; +5. a `DataFrame` created from a dictionary of students and scores. + +Nothing is written to disk unless you ask for it. To also export the scores table +to a CSV file, give a path: + +```bash +python -m weather --export new_data.csv +``` + +If `pandas` is not installed the `csv` part is still printed, a message names the +extra to install, and the exit code is 1. + +The functions can also be used from your own code: + +```python +from weather.csv_reader import read_temperatures +from weather.analysis import read_data, average_temp, max_temp + +temperatures = read_temperatures() # [12, 14, 15, 14, 21, 22, 24] +data = read_data() # a pandas DataFrame +print(average_temp(data), max_temp(data)) +``` + +The default data file is the `weather_data.csv` inside the package, so the +functions work from any folder; pass a `path` to read another file. + +## Run the tests + +The tests write only into temporary folders. + +```bash +pytest +``` + +The same checks that continuous integration runs: + +```bash +python -m pytest +python -m ruff check src tests +python -m ruff format --check src tests +python -m mypy +``` + +## Continuous integration + +`.gitea/workflows/ci.yml` runs on Gitea Actions on every push and on every pull +request. It sets up Python 3.13, upgrades `pip`, installs `.[dev]`, then runs +`pytest`, `ruff` (lint and format check) and `mypy`. It does not build the source +documentation: run `doxygen Doxyfile` yourself, as the next section shows. + +The workflow lives in `.gitea/workflows` and not in `.github/workflows`, so +GitHub does not run it and pushing to a GitHub mirror needs no workflow +permission. + +## Build the source documentation + +The source is documented with Doxygen comments and the `Doxyfile` in the root. +Install Doxygen (`winget install DimitriVanHeesch.Doxygen` on Windows, +`sudo apt install doxygen` on Debian, `brew install doxygen` on macOS), then: + +```bash +doxygen Doxyfile +``` + +The HTML is written to `build/doxygen/index.html`. A warning fails the build. + +## Project layout + +```text +. +├── .gitea/workflows/ci.yml continuous integration (Gitea Actions) +├── docs/ business case, plan, milestones, reviews, screenshot +├── src/weather/ the package +│ ├── __init__.py +│ ├── __main__.py prints the results: python -m weather +│ ├── analysis.py read_data, average_temp, max_temp, row selection (pandas) +│ ├── constants.py every constant of the lectures +│ ├── csv_reader.py read_rows and read_temperatures (csv library) +│ ├── export.py create_scores_frame and export_frame (pandas) +│ └── weather_data.csv the weather data of the lecture +├── tests/ pytest tests (conftest.py runs every test in a +│ temporary folder) +├── wiki/ wiki pages in English, Danish and Bahasa Melayu +├── Doxyfile source documentation settings +├── LICENSE +├── pyproject.toml project configuration +└── README.md +``` + +## License + +GNU Affero General Public License v3.0 only. See [LICENSE](LICENSE).