# League Manager
<img src="https://codeberg.org/attachments/ee21b5d5-73b4-4f16-84be-c1c70f414ec3" width="250px">
## Table of Contents
- [About](#about)
- [Background](#background)
- [Getting Started](#getting_started)
- [Installing From git](#installing_from_git)
- [Installing Dependencies](#installing_dependencies)
- [Installing From pip](#installing_from_pip)
- [CLI Usage](#usage)
- [Initializing The Database](initializing_database)
- [What Next](#what_next)
- [Contributing](#contributing)
## About 📚 <a name = "about"></a>
**League Manager** allows you to create and manage seasons, leagues, teams, players, and more.
First, define a season that establish when the competition will begin. Next, create one or more leagues (and corresponding teams) to attach to that season.
Then you will be able to auto-generate a weekly schedule based on the number of fixtures/matches within that season.
You can also create one-off fixtures/matches on the schedule. Track results and auto-update a standings table.
### Background 🔍 <a name = "background"></a>
League Manager is built around [Advanced Alchemy](https://docs.advanced-alchemy.litestar.dev/latest/), which itself is a companion library for [SQLAlchemy](https://www.sqlalchemy.org) and [Alembic](https://alembic.sqlalchemy.org/en/latest/).
In also uses the awesome [svcs library](https://svcs.hynek.me/en/stable/) as a way of managing the database services and serving them up as needed, eliminating much of the boilerplate you would have to do on your own.
As such, League Manager is designed to ease the hurdle of setting up database models, migrations, and a multitude of operations/features common to many CRUD applications.
## Getting Started 🚀 <a name = "getting_started"></a>
Keep in mind that League Manager is a work in progress, and some of these instructions might change.
However, you are welcome to check out the license and [contribution guide](https://codeberg.org/pythonbynight/leaguemanager/src/branch/main/CONTRIBUTING.md).
### Installing From git 💻 <a name = "install_from_git"></a>
If you want to work on League Manager or contribute to the project, you can install from the git repository:
```sh
git clone https://git@codeburg.com:pythonbynight/leaguemanager
cd leaguemanager
```
### Installing Dependencies 📦 <a name = "installing_dependencies"></a>
Next, you will need to install the dependencies, and `leaguemanager` itself. I recommend using `uv` for dependency management.
You should be able to download `uv` using a curl command:
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```
If you previously installed `uv`, you can upgrade to the latest version.
```sh
uv self update
```
Once `uv` is installed, you can install the project dependencies.
```sh
uv sync
```
This should create a virtual environment and install all the project dependencies.
### Installing From pip 📈 <a name = "installing_from_pip"></a>
If, instead, you want to _use_ League Manager as a dependency for your own project, you can also install the package via pip.
I would recommend starting a new project and creating/activating a virtual environment first.
```sh
# Create a new project and virtual environment
mkdir my-project
cd my-project
python -m venv .venv
# On Linux/MacOS
source .venv/bin/activate
# Or Windows
.venv/Scripts/activate
```
Then install with pip:
```shell
python -m pip install leaguemanager
```
> Note: You can also use `uv` to install from the repository. The command is:
>
> `uv add leaguemanager`
This allows you to incorporate League Manager into your own application. The CLI can still be used as shown below. You also have access to existing database features and commands (migrations/operations/etc...).
## CLI Usage 🖥️ <a name = "cli_usage"></a>
The CLI command for League Manager is `mgr`
To access the help screen, type in the command as is, or with `--help`
> Note: If you have intstalled `leaguemanager` as a dependency to your project, make sure to create a .py file in your new project, or the CLI command might fail.
```sh
# this accesses the help menu
mgr
# this does as well
mgr --help
```
> Note: Running this command for the first time will create a directory for database data (`data_league_db`). It will stay empty unless you take the following steps.
### Initializing The Database 🔄 <a name = "initializing_database">
Before getting started, you will want to set up your database. League Manager has sqlite support out of the box, and incorporates [Alembic commands](https://alembic.sqlalchemy.org/en/latest/api/commands.html) straight from [Advanced Alchemy](https://docs.advanced-alchemy.litestar.dev/latest/).
You _can_ set a couple of environment variables if you wish to customize where the database file is located, as well as to where the Alembic-related files are created.
However, the CLI will work out of the box with sensible defaults.
All the Alembic commands, managed through Advanced Alchemy, are contained within the `db` subgroup. You can get a list of all those commands by typing:
```sh
mgr db
```
To fire up your database, you will need to type the following commands:
```sh
# This equates to `alembic init` command.
# It creates a "migrations" directory.
# You only need to do this once.
mgr db init migrations
# This builds migration files into the new directory.
# Run this command after making changes to models.
mgr db make-migrations
# This command writes the League Manager tables to the database
# Always run this command after `make-migrations`
mgr db upgrade
```
This sequence of commands will get your database ready to go. Again, they mimic the commands you would ordinarily use with Alembic, but you have no need to install or run Alembic independently (though you can do that too if you wish).
Lastly, although the tables are set up for you, they currently hold no data.
League Manager comes with a small set of synthetic data (in raw json) that can be used to populate the database. (This is a League Manager command, so no need to include the `db` subgroup command):
```sh
# Populate the database with synthetic data
mgr populate
```
If you want to make sure that the tables have been created:
```sh
# Check the "count" of how many rows of data in each table
mgr check --all
```
And lastly, if you want to delete the synthetic data:
```sh
# Delete all the things
mgr delete --all
```
If you actually want to _drop the tables_ from the database, you can once agan refer to the Advanced Alchemy command group (prefaced with `db`) like so:
```sh
mgr db drop-all
```
## What Next 🤔 <a name = "what_next"></a>
League Manager comes with several models, currently skewed toward running _soccer_ leagues, but it can still work with other sports/genres, specifically to generate round-robin style schedules and fixtures/matches.
Under the hood, the library utilizes the [svcs library](https://svcs.hynek.me/en/stable/) to serve up a database session, as well as preconfigured database services offering easy-to-use, preconfigured CRUD operations on each of the provided models.
More documentation on that process will follow. But in short, if you want to access the services:
```python
from leaguemanager.dependency import LeagueManagerRegistry
from leaguemanager.services import SeasonSyncService, TeamSyncService
registry = LeagueManagerRegistry()
season_service = registry.provide_db_service(SeasonSyncService)
team_service = registry.provide_db_service(TeamSyncService)
# This will return the number of seasons saved in the database
number_of_seasons = season_service.count()
# This will return a list of `Season` objects (models)
seasons = season_service.list()
# Total number of teams in the database
number_of_teams = team_service.count()
# You get the idea
teams = team_service.list()
# Print all the team names
for team in teams:
print(team.name)
```
The `provide_db_service` is able to look at the `type` of service passed in, and now you have access to many typical CRUD operations and filters for that specific table. Some of the services also include additional business logic specific to League Manager applications.
If you only need the database session (a SQLAlchemy `Session` type) to do your own custom logic using SQLAlchemy, you can also use the registry.
```py
# Using the db session directly
session = registry.provide_db_session
session.execute(delete(SomeModel))
```
## Contributing 🤝 <a name = "contributing"></a>
Hey, you made it down to here! Do you like what you see? Think you can help a bit?
If you would like to contribute, please refer to the [contribution guide](https://codeberg.org/pythonbynight/leaguemanager/src/branch/main/CONTRIBUTING.md) for details on how to help.
Raw data
{
"_id": null,
"home_page": null,
"name": "leaguemanager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "advanced alchemy, alembic, league, sports, sqlalchemy",
"author": null,
"author_email": "Mario Munoz <pythonbynight@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6a/4f/0cf39da82aba790ad2e025a2f330ef7889f3226093a65cf6dc83f34c91b6/leaguemanager-0.2.2.tar.gz",
"platform": null,
"description": "# League Manager\n\n<img src=\"https://codeberg.org/attachments/ee21b5d5-73b4-4f16-84be-c1c70f414ec3\" width=\"250px\">\n\n## Table of Contents\n\n- [About](#about)\n - [Background](#background)\n- [Getting Started](#getting_started)\n - [Installing From git](#installing_from_git)\n - [Installing Dependencies](#installing_dependencies)\n - [Installing From pip](#installing_from_pip)\n- [CLI Usage](#usage)\n - [Initializing The Database](initializing_database)\n- [What Next](#what_next)\n- [Contributing](#contributing)\n\n\n## About \ud83d\udcda <a name = \"about\"></a>\n\n**League Manager** allows you to create and manage seasons, leagues, teams, players, and more. \n\nFirst, define a season that establish when the competition will begin. Next, create one or more leagues (and corresponding teams) to attach to that season. \n\nThen you will be able to auto-generate a weekly schedule based on the number of fixtures/matches within that season. \n\nYou can also create one-off fixtures/matches on the schedule. Track results and auto-update a standings table.\n\n### Background \ud83d\udd0d <a name = \"background\"></a>\n\nLeague Manager is built around [Advanced Alchemy](https://docs.advanced-alchemy.litestar.dev/latest/), which itself is a companion library for [SQLAlchemy](https://www.sqlalchemy.org) and [Alembic](https://alembic.sqlalchemy.org/en/latest/).\n\nIn also uses the awesome [svcs library](https://svcs.hynek.me/en/stable/) as a way of managing the database services and serving them up as needed, eliminating much of the boilerplate you would have to do on your own.\n\nAs such, League Manager is designed to ease the hurdle of setting up database models, migrations, and a multitude of operations/features common to many CRUD applications.\n\n\n## Getting Started \ud83d\ude80 <a name = \"getting_started\"></a>\n\nKeep in mind that League Manager is a work in progress, and some of these instructions might change.\n\nHowever, you are welcome to check out the license and [contribution guide](https://codeberg.org/pythonbynight/leaguemanager/src/branch/main/CONTRIBUTING.md).\n\n### Installing From git \ud83d\udcbb <a name = \"install_from_git\"></a>\n\nIf you want to work on League Manager or contribute to the project, you can install from the git repository:\n\n```sh\ngit clone https://git@codeburg.com:pythonbynight/leaguemanager\ncd leaguemanager\n```\n\n\n### Installing Dependencies \ud83d\udce6 <a name = \"installing_dependencies\"></a>\n\nNext, you will need to install the dependencies, and `leaguemanager` itself. I recommend using `uv` for dependency management.\n\nYou should be able to download `uv` using a curl command:\n\n```sh\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\nIf you previously installed `uv`, you can upgrade to the latest version.\n\n```sh\nuv self update\n```\n\nOnce `uv` is installed, you can install the project dependencies.\n\n```sh\nuv sync\n```\n\nThis should create a virtual environment and install all the project dependencies.\n\n### Installing From pip \ud83d\udcc8 <a name = \"installing_from_pip\"></a>\n\nIf, instead, you want to _use_ League Manager as a dependency for your own project, you can also install the package via pip.\n\nI would recommend starting a new project and creating/activating a virtual environment first.\n\n```sh\n# Create a new project and virtual environment\n\nmkdir my-project\ncd my-project\npython -m venv .venv\n\n# On Linux/MacOS\nsource .venv/bin/activate\n\n# Or Windows\n.venv/Scripts/activate\n```\n\nThen install with pip:\n\n```shell\npython -m pip install leaguemanager\n```\n\n> Note: You can also use `uv` to install from the repository. The command is:\n>\n> `uv add leaguemanager`\n\nThis allows you to incorporate League Manager into your own application. The CLI can still be used as shown below. You also have access to existing database features and commands (migrations/operations/etc...).\n\n## CLI Usage \ud83d\udda5\ufe0f <a name = \"cli_usage\"></a>\n\nThe CLI command for League Manager is `mgr`\n\nTo access the help screen, type in the command as is, or with `--help`\n\n> Note: If you have intstalled `leaguemanager` as a dependency to your project, make sure to create a .py file in your new project, or the CLI command might fail.\n\n```sh\n# this accesses the help menu\nmgr\n\n# this does as well\nmgr --help\n```\n\n> Note: Running this command for the first time will create a directory for database data (`data_league_db`). It will stay empty unless you take the following steps.\n\n### Initializing The Database \ud83d\udd04 <a name = \"initializing_database\">\n\nBefore getting started, you will want to set up your database. League Manager has sqlite support out of the box, and incorporates [Alembic commands](https://alembic.sqlalchemy.org/en/latest/api/commands.html) straight from [Advanced Alchemy](https://docs.advanced-alchemy.litestar.dev/latest/). \n\nYou _can_ set a couple of environment variables if you wish to customize where the database file is located, as well as to where the Alembic-related files are created.\n\nHowever, the CLI will work out of the box with sensible defaults. \n\nAll the Alembic commands, managed through Advanced Alchemy, are contained within the `db` subgroup. You can get a list of all those commands by typing:\n\n```sh\nmgr db\n```\n\nTo fire up your database, you will need to type the following commands:\n\n```sh\n# This equates to `alembic init` command. \n# It creates a \"migrations\" directory.\n# You only need to do this once.\nmgr db init migrations\n\n# This builds migration files into the new directory.\n# Run this command after making changes to models.\nmgr db make-migrations\n\n# This command writes the League Manager tables to the database\n# Always run this command after `make-migrations`\nmgr db upgrade\n```\n\nThis sequence of commands will get your database ready to go. Again, they mimic the commands you would ordinarily use with Alembic, but you have no need to install or run Alembic independently (though you can do that too if you wish). \n\nLastly, although the tables are set up for you, they currently hold no data.\n\nLeague Manager comes with a small set of synthetic data (in raw json) that can be used to populate the database. (This is a League Manager command, so no need to include the `db` subgroup command):\n\n```sh\n# Populate the database with synthetic data\nmgr populate\n```\n\nIf you want to make sure that the tables have been created:\n\n```sh\n# Check the \"count\" of how many rows of data in each table\nmgr check --all\n```\n\nAnd lastly, if you want to delete the synthetic data:\n\n```sh\n# Delete all the things\nmgr delete --all\n```\n\nIf you actually want to _drop the tables_ from the database, you can once agan refer to the Advanced Alchemy command group (prefaced with `db`) like so:\n\n```sh\nmgr db drop-all\n```\n\n## What Next \ud83e\udd14 <a name = \"what_next\"></a>\n\nLeague Manager comes with several models, currently skewed toward running _soccer_ leagues, but it can still work with other sports/genres, specifically to generate round-robin style schedules and fixtures/matches.\n\nUnder the hood, the library utilizes the [svcs library](https://svcs.hynek.me/en/stable/) to serve up a database session, as well as preconfigured database services offering easy-to-use, preconfigured CRUD operations on each of the provided models.\n\nMore documentation on that process will follow. But in short, if you want to access the services:\n\n```python\nfrom leaguemanager.dependency import LeagueManagerRegistry\nfrom leaguemanager.services import SeasonSyncService, TeamSyncService\n\nregistry = LeagueManagerRegistry()\nseason_service = registry.provide_db_service(SeasonSyncService)\nteam_service = registry.provide_db_service(TeamSyncService)\n\n# This will return the number of seasons saved in the database\nnumber_of_seasons = season_service.count()\n\n# This will return a list of `Season` objects (models)\nseasons = season_service.list()\n\n# Total number of teams in the database\nnumber_of_teams = team_service.count()\n\n# You get the idea\nteams = team_service.list()\n\n# Print all the team names\nfor team in teams:\n print(team.name)\n```\n\nThe `provide_db_service` is able to look at the `type` of service passed in, and now you have access to many typical CRUD operations and filters for that specific table. Some of the services also include additional business logic specific to League Manager applications.\n\nIf you only need the database session (a SQLAlchemy `Session` type) to do your own custom logic using SQLAlchemy, you can also use the registry.\n\n```py\n# Using the db session directly\n\nsession = registry.provide_db_session\n\nsession.execute(delete(SomeModel))\n```\n\n\n## Contributing \ud83e\udd1d <a name = \"contributing\"></a>\n\nHey, you made it down to here! Do you like what you see? Think you can help a bit?\n\nIf you would like to contribute, please refer to the [contribution guide](https://codeberg.org/pythonbynight/leaguemanager/src/branch/main/CONTRIBUTING.md) for details on how to help.",
"bugtrack_url": null,
"license": null,
"summary": "Build and manage sports leagues.",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://codeberg.org/pythonbynight/leaguemanager",
"Issue": "https://codeberg.org/pythonbynight/leaguemanager/issues",
"Source": "https://codeberg.org/pythonbynight/leaguemanager"
},
"split_keywords": [
"advanced alchemy",
" alembic",
" league",
" sports",
" sqlalchemy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "979eaa7e30c9cb29e3f4dba5c4bcb4ac594bd75419cd9081125b31f019dcadfb",
"md5": "a08383eb7b46b99e08eaf9b4b448d250",
"sha256": "723a17334c032d5f3e16de4a9bffb7cb76b0c25e98904e8239bae90292b5aaf4"
},
"downloads": -1,
"filename": "leaguemanager-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a08383eb7b46b99e08eaf9b4b448d250",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 58339,
"upload_time": "2025-01-22T19:48:36",
"upload_time_iso_8601": "2025-01-22T19:48:36.595816Z",
"url": "https://files.pythonhosted.org/packages/97/9e/aa7e30c9cb29e3f4dba5c4bcb4ac594bd75419cd9081125b31f019dcadfb/leaguemanager-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6a4f0cf39da82aba790ad2e025a2f330ef7889f3226093a65cf6dc83f34c91b6",
"md5": "c24fd417a8be6b2da901407697cddd28",
"sha256": "6b18bdf998a1137199915e0982481560359c7f1bca5af9f9489b2c71da089c81"
},
"downloads": -1,
"filename": "leaguemanager-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "c24fd417a8be6b2da901407697cddd28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 92896,
"upload_time": "2025-01-22T19:48:38",
"upload_time_iso_8601": "2025-01-22T19:48:38.706563Z",
"url": "https://files.pythonhosted.org/packages/6a/4f/0cf39da82aba790ad2e025a2f330ef7889f3226093a65cf6dc83f34c91b6/leaguemanager-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-22 19:48:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "pythonbynight",
"codeberg_project": "leaguemanager",
"lcname": "leaguemanager"
}
JSON