Overview

This repository defines the F3 data structure, used by the F3 Slack Bot, Maps, etc. The projected uses SQLAlchemy to define the tables / models.

Running Locally

To load the data structure in your database:

Set up a local db, update .env.example and save as .env
Clone the repo, use Poetry to install dependencies:

poetry env use 3.12
poetry install

Run the alembic migration:

source .env && poetry run alembic upgrade head

Optional BigQuery Sessions

The default database session path is PostgreSQL. To explicitly request a BigQuery session, pass the optional backend argument:

from f3_data_models.utils import get_session

postgres_session = get_session()
bigquery_session = get_session(backend="bigquery")

session_scope(...) and DbManager methods also accept the same optional backend argument.

BigQuery mode requires these environment variables:

BIGQUERY_PROJECT
BIGQUERY_DATASET

Authentication should be provided through Google Application Default Credentials in the runtime environment.

Contributing

If you would like to make a change, you will need to:

Make the change in models.py
Make a alembic revision:

source .env && alembic revision --autogenerate -m "Your Message Here"

Make any edits to the migration script in alembic/versions
Run the upgrade on your local db:

source .env && alembic upgrade head

Bump the version on pyproject.toml:

poetry version patch[minor][major]

Tag your final commit and make sure to push those tags to trigger the pypi package build:

git tag <new_version> -a -m "Your message here"
git push origin --tags

[!NOTE] The github pages documentation will be updated when you push to main, but if you would like to preview locally, run:

poetry run sphinx-build -b html docs docs/_build/html
cd docs
poetry run python -m http.server --directory _build/html

[!TIP]
Adding new fields as nullable (ie Optional[]) has the best chance of reducing breaking changes to the apps.

Entity Overview

---
config:
    look: handDrawn
    theme: dark
---

erDiagram
    USERS ||--|{ ATTENDANCE : have
    ATTENDANCE }|--|| EVENT_INSTANCES: at
    ATTENDANCE }|..|{ ATTENDANCE_TYPES : "are of type(s)"
    EVENT_INSTANCES }|..|| EVENTS : "part of series"
    EVENT_INSTANCES }|..|{ EVENT_TYPES : "with type(s)"
    EVENTS }|..|{ EVENT_TYPES : "with type(s)"
    EVENT_INSTANCES }|--|| ORGS : "belong to"
    EVENT_INSTANCES }|..|| LOCATIONS : "at"
    EVENTS }|--|| ORGS : "belong to"
    EVENTS }|..|| LOCATIONS : "at"
    SLACK_SPACES ||..|| ORGS : "are connected to"
    USERS ||..|{ SLACK_USERS : "have one or more"
    SLACK_USERS }|--|| SLACK_SPACES : "belong to"
    USERS }|..|{ ACHIEVEMENTS : "earn"
    USERS }|..|{ ROLES : "have"
    ROLES ||..|{ PERMISSIONS : "have"
    ROLES }|..|{ ORGS : "in"
    USERS }|..|{ POSITIONS : "hold"
    POSITIONS }|..|{ ORGS : "in"

Metadata

Release files for f3-data-models 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for f3-data-models 1.2.1
File	Size	Uploaded
f3_data_models-1.2.1.tar.gz	17.7 kB	Jun 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for f3-data-models 1.2.1
File	Interpreter	ABI	Platform	Reset
f3_data_models-1.2.1-py3-none-any.whl 17.2 kB Jun 16, 2026	Python 3	none	any	Details

Total release size: 34.9 kB

Release files / f3_data_models-1.2.1.tar.gz

Download URL	f3_data_models-1.2.1.tar.gz
Size	17.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`ac8dfba929961a06827acb3ed7c4de80323d1af22a63180672c21f63afa2697c`
BLAKE2b-256 checksum How to use checksums	`d899530975fc83ef96689a157181e5dbde96e4a202cdf22767f48801ed6b0719`
Upload date	Jun 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.12.1 Linux/6.17.0-1018-azure`

Release files / f3_data_models-1.2.1-py3-none-any.whl

Download URL	f3_data_models-1.2.1-py3-none-any.whl
Size	17.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2f4699067aacfebf8f433ef1db61f898abe2ef067e580ed889656f8cf4fa9acb`
BLAKE2b-256 checksum How to use checksums	`c867c8efcfee673df43a581c3352c08ceb331b65363f22b1a261de2955118728`
Upload date	Jun 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.12.1 Linux/6.17.0-1018-azure`