Implementing client.account.get_timeline()

.github/dependabot.yml

@@ -1,4 +1,4 @@
-# Set update schedule for GitHub Actions
+# Set update schedule for GitHub Actions and Python dependencies
 
 version: 2
 updates:
@@ -8,3 +8,16 @@ updates:
     schedule:
       # Check for updates to GitHub Actions every week
       interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      # Check for updates to Python dependencies every week
+      interval: "weekly"
+    # Only check runtime dependencies, not dev dependencies
+    # Dependabot only checks the main dependencies array in pyproject.toml
+    # and ignores dependency-groups by default
+    groups:
+      dependencies:
+        patterns:
+          - "*"

.github/workflows/integration_test.yml

@@ -19,25 +19,14 @@ on:
 
 jobs:
   lila:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
-    container: ubuntu:latest
-    services:
-      bdit_lila:
-        image: ghcr.io/lichess-org/lila-docker:main
-        options: --restart=always
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v5
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install make and curl
-        run: apt update && apt install -y make curl
-      - name: Install dependencies
-        run: make setup
+        uses: astral-sh/setup-uv@v7 # latest
       - name: Run integration tests
         run: |
-          ./integration/run-tests.sh
+          ./integration/local.py --python ${{ matrix.python-version }}

.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Publish to Pypi (and testPypi)
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: 'bump version: major, minor, patch, or none to build current dev'
+        required: true
+        type: choice
+        options:
+          - none
+          - major
+          - minor
+          - patch
+      environment:
+        description: 'Target environment: testpypi or pypi'
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: 'testpypi'
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    env:
+      BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+
+    steps:
+    - uses: actions/checkout@v5
+    - name: Configure Git
+      run: |
+        git config user.name github-actions
+        git config user.email github-actions@github.com
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+    - name: Build berserk package
+      run: uv run release.py --bump ${{ github.event.inputs.bump }} --branch ${{ env.BRANCH_NAME }}
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish:
+    name: Publish to ${{ github.event.inputs.environment }}
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    if: github.event.inputs.environment == 'testpypi' || github.event.inputs.environment == 'pypi'
+
+    environment:
+      name: ${{ github.event.inputs.environment }}
+      url: ${{ github.event.inputs.environment == 'testpypi' && 'https://test.pypi.org/p/berserk' || 'https://pypi.org/p/berserk' }}
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish to ${{ github.event.inputs.environment }}
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: ${{ github.event.inputs.environment == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}

.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:

.github/workflows/typing.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5

CHANGELOG.rst

@@ -4,9 +4,23 @@ Changelog
 To be released
 --------------
 
+
+* Deprecate Python 3.9 support - minimum required version is now Python 3.10+. This does not mean the library will not work with Python 3.9, but it will not be tested against it anymore.
+
 * Added ``pgn_in_json`` parameter to ``client.games.export``.
+* Implement `broadcasts.get_top()` endpoint; typing fixes and validation.
+* Added ``client.relations.block`` and ``client.relations.unblock`` for blocking/unblocking users.
+* Implemented ``/api/games/export/imports`` under
+  ``client.games.export_imported``.
+* Added ``client.account.get_timeline`` to get current logged user timeline.
+
+Thanks to all the contributors who helped to this release:
+- @hsheth2
+- @DoraFgr
+- @MrElyazid
+- @gameroman
+- @JAMoreno-Larios
 
-Thanks to @hsheth2 for their contributions to this release.
 
 v0.14.0 (2025-08-26)
 --------------------

CONVENTIONS.md

@@ -0,0 +1,3 @@
+- use types everywhere
+- NEVER use `try` and `except` blocks
+- use as few logging as possible

Makefile

@@ -24,7 +24,10 @@ clean-test: ## remove test and coverage artifacts
 	rm -fr .pytest_cache
 
 setup: ## setup uv env and install dependencies
-	uv sync
+	uv sync --locked
+
+setup-ci: ## for Docker, install the deps only. need to run `setup` after
+	uv sync --locked --no-install-project
 
 test: ## run tests with pytest
 	uv run pytest tests
@@ -33,14 +36,13 @@ test_record: ## run tests with pytest and record http requests
 	uv run pytest --record-mode=once
 
 typecheck: ## run type checking with pyright
-	uv run pyright berserk
+	uv run pyright berserk integration/local.py
 
-format: ## format python files with black and docformatter
-	uv run black berserk tests check-endpoints.py release.py
-	uv run docformatter --in-place --black berserk/*.py
+format: ## format python files with ruff
+	uv run ruff format
 
-format-check: ## check formatting with black (for CI)
-	uv run black berserk tests check-endpoints.py release.py --check
+format-check: ## check formatting with ruff (for CI)
+	uv run ruff format . --diff
 
 docs: ## generate Sphinx HTML documentation, including API docs
 	uv run sphinx-build -b html docs _build -EW --keep-going

README.rst

@@ -26,7 +26,7 @@ This is based on the `original berserk version created by rhgrant10 <https://git
 Installation
 ------------
 
-Requires Python 3.9+. Download and install the latest release:
+Requires Python 3.10+. Download and install the latest release:
 ::
 
     pip3 install berserk
@@ -70,6 +70,7 @@ Most of the API is available:
     client.account.get_kid_mode
     client.account.set_kid_mode
     client.account.upgrade_to_bot
+    client.account.get_timeline
 
     client.analysis.get_cloud_evaluation
 
@@ -113,6 +114,7 @@ Most of the API is available:
     client.broadcasts.get_round_pgns
     client.broadcasts.get_pgns
     client.broadcasts.stream_round
+    client.broadcasts.get_top
 
     client.bulk_pairings.get_upcoming
     client.bulk_pairings.create
@@ -150,6 +152,7 @@ Most of the API is available:
     client.games.export_ongoing_by_player
     client.games.export_by_player
     client.games.export_multi
+    client.games.export_imported
     client.games.get_among_players
     client.games.stream_games_by_ids
     client.games.add_game_ids_to_stream
@@ -173,6 +176,8 @@ Most of the API is available:
     client.relations.get_users_followed
     client.relations.follow
     client.relations.unfollow
+    client.relations.block
+    client.relations.unblock
 
     client.simuls.get
 

berserk/__init__.py

@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """Top-level package for berserk."""
 
 from importlib import metadata

berserk/clients/account.py

@@ -3,7 +3,7 @@
 from typing import cast
 
 from .. import models
-from ..types.account import AccountInformation, Preferences
+from ..types.account import AccountInformation, Preferences, Timeline
 from .base import BaseClient
 
 
@@ -60,3 +60,15 @@ def upgrade_to_bot(self):
         """
         path = "/api/bot/account/upgrade"
         self._r.post(path)
+
+    def get_timeline(self, since: int = 1356998400070, nb: int = 15) -> Timeline:
+        """
+        Get the timeline events of the logged in user.
+        Requires OAuth2 authorization.
+
+        :param since: shows events since the provided timestamp, default
+            1356998400070 (the earliest allowed by Lichess
+        :param nb: Max number of events to fetch, default 15.
+        """
+        path = "/api/timeline"
+        return cast(Timeline, self._r.get(path))

berserk/clients/broadcasts.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
-from typing import Iterator, Any, Dict, List
+from typing import Iterator, Any, Dict, List, cast
 
 from .. import models
 from ..formats import PGN
 from .base import BaseClient
 
-from ..types.broadcast import BroadcastPlayer
+from ..types.broadcast import BroadcastPlayer, BroadcastTop
 from ..utils import to_str
 
 
@@ -244,3 +244,18 @@ def stream_my_rounds(self, nb: int | None = None) -> Iterator[Dict[str, Any]]:
         path = "/api/broadcast/my-rounds"
         params = {"nb": nb}
         yield from self._r.get(path, params=params, stream=True)
+
+    def get_top(
+        self,
+        page: int = 1,
+        html: bool = False,
+    ) -> BroadcastTop:
+        """Return the paginated top broadcasts structure for `page`.
+
+        :param page: which page to fetch (1..20). Only page 1 has `active` broadcasts.
+        :param html: if True, convert the `description` field from markdown to HTML.
+        :return: parsed JSON response with keys `active` and `past`.
+        """
+        path = "/api/broadcast/top"
+        params = {"page": page, "html": html}
+        return cast(BroadcastTop, self._r.get(path, params=params))

berserk/clients/games.py

@@ -317,3 +317,14 @@ def import_game(self, pgn: str) -> Dict[str, Any]:
             "pgn": pgn,
         }
         return self._r.post(path, data=payload)
+
+    def export_imported(self) -> str:
+        """
+        Export all the imported games by the currently logged in user
+        as a PGN.
+        Requires OAuth2 authorization.
+
+        :return: the exported games in a single string
+        """
+        path = "/api/games/export/imports"
+        return self._r.get(path, fmt=PGN, stream=False)

berserk/clients/relations.py

@@ -33,3 +33,19 @@ def unfollow(self, username: str):
         """
         path = f"/api/rel/unfollow/{username}"
         self._r.post(path)
+
+    def block(self, username: str):
+        """Block a player.
+
+        :param username: user to block
+        """
+        path = f"/api/rel/block/{username}"
+        self._r.post(path)
+
+    def unblock(self, username: str):
+        """Unblock a player.
+
+        :param username: user to unblock
+        """
+        path = f"/api/rel/unblock/{username}"
+        self._r.post(path)

berserk/types/account.py

@@ -2,7 +2,8 @@
 
 from datetime import datetime
 
-from typing_extensions import TypedDict, TypeAlias, Literal
+from typing_extensions import TypedDict, TypeAlias, Literal, NotRequired
+from .common import LightUser
 
 
 class Perf(TypedDict):
@@ -120,3 +121,14 @@ class UserPreferences(TypedDict, total=False):
 class Preferences(TypedDict):
     prefs: UserPreferences
     language: str
+
+
+class TimelineEntry(TypedDict):
+    type: NotRequired[str]
+    data: NotRequired[dict[str, str] | None]
+    date: int
+
+
+class Timeline(TypedDict):
+    entries: list[TimelineEntry]
+    users: dict[str, LightUser]