add precomit and ticket analytics view

Author: baraline

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.13
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

CONTRIBUTING.md

@@ -8,14 +8,21 @@ Thank you for improving `glpi-python-client`.
 python -m venv .venv
 .venv\Scripts\activate
 python -m pip install -e .[dev]
+python -m pre_commit install
+python -m pre_commit run --all-files
 python -m pytest
 ```
 
+The repository ships a root `.pre-commit-config.yaml` that runs Ruff on each
+commit. The lint hook applies safe fixes first, then Ruff formats the touched
+files.
+
 ## Quality Checks
 
 Run the focused checks before opening a pull request:
 
 ```bash
+python -m pre_commit run --all-files
 python -m pytest
 python -m ruff check .
 python -m mypy glpi_python_client
@@ -26,7 +33,7 @@ python -m mypy glpi_python_client
 To build the documentation locally:
 
 ```bash
-python -m sphinx -W --keep-going -b html docs docs/_build/html pa
+python -m sphinx -W --keep-going -b html docs docs/_build/html
 ```
 
 ## GitHub Actions

conftest.py

@@ -1 +1 @@
-pytest_plugins = ("glpi_python_client.testing.fixtures",)
+pytest_plugins = ("glpi_python_client.testing.fixtures",)

docs/api_reference.rst

@@ -30,6 +30,11 @@ Legacy v1 Session
 Models
 ------
 
+.. autoclass:: GlpiEntity
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. autoclass:: GlpiUser
    :members:
    :undoc-members:
@@ -70,6 +75,29 @@ Models
    :undoc-members:
    :show-inheritance:
 
+.. autoclass:: GlpiTicketContext
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Enums
+-----
+
+.. autoclass:: GlpiTicketStatus
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GlpiPriority
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GlpiTicketType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Package Metadata
 ----------------
 

docs/development.md

@@ -9,13 +9,19 @@ python -m venv .venv
 .venv\Scripts\activate
 python -m pip install --upgrade pip
 python -m pip install -e .[dev]
+python -m pre_commit install
 ```
 
+The repository ships a root `.pre-commit-config.yaml` that runs Ruff on each
+commit. The lint hook applies safe fixes first, then Ruff formats the touched
+files.
+
 ## Checks
 
 Run these before publishing or opening a pull request:
 
 ```bash
+python -m pre_commit run --all-files
 python -m pytest
 python -m ruff check .
 python -m mypy glpi_python_client

docs/development_rtd.rst

@@ -12,6 +12,11 @@ Create a virtual environment and install the development dependencies:
    .venv\Scripts\activate
    python -m pip install --upgrade pip
    python -m pip install -e .[dev]
+   python -m pre_commit install
+
+The repository ships a root ``.pre-commit-config.yaml`` that runs Ruff on each
+commit. The lint hook applies safe fixes first, then Ruff formats the touched
+files.
 
 Quality Checks
 --------------
@@ -20,6 +25,7 @@ Run the focused checks before opening a pull request:
 
 .. code-block:: console
 
+   python -m pre_commit run --all-files
    python -m pytest
    python -m ruff check .
    python -m mypy glpi_python_client

docs/usage.md

@@ -138,6 +138,42 @@ category. If your GLPI workflow requires any of those values, set them on
 `status`, `type`, `category`, `location`, `date_creation`, `date_mod`,
 `date_close`, `user_recipient`, `user_editor`, and `team`.
 
+When you request extra ticket fields that do not map to typed `GlpiTicket`
+attributes, the package preserves them in `ticket.extra_payload` instead of
+dropping them. This keeps the modeled fields typed while still exposing the raw
+requested GLPI keys through a public field.
+
+```python
+tickets = glpi.search_ticket_records(
+    query='status.id=in=(1,2)',
+    fields=("resolution_date", "date_solve"),
+)
+
+first_ticket = tickets[0]
+print(first_ticket.extra_payload["resolution_date"])
+print(first_ticket.extra_payload["date_solve"])
+```
+
+## Entities
+
+Use `search_entities()` when you need typed entity lookup from the public
+package root.
+
+```python
+from glpi_python_client import GlpiEntity
+
+entities = glpi.search_entities(
+    rsql_filter='name=like=*novahe*',
+    limit=50,
+    start=0,
+)
+
+for entity in entities:
+    print(entity.entity_id, entity.name, entity.complete_name)
+```
+
+Unmodeled entity payload keys are preserved in `GlpiEntity.extra_payload`.
+
 ## Models and Content Formatting
 
 Public GLPI objects are field-validated Pydantic models. Create and update GLPI
@@ -204,6 +240,78 @@ solutions = glpi.get_solution_records("123")
 Public client methods accept GLPI identifiers as either `str` or `int` and
 normalize them into request paths as needed.
 
+## Tasks And Duration Statistics
+
+Use `search_task_records()` for global task searches and `get_task_durations()`
+when you need aggregated duration reports.
+
+```python
+tasks = glpi.search_task_records(
+    query='date=ge=2026-01-01;date=le=2026-01-31',
+    fields=("id", "tickets_id", "users_id", "actiontime", "date", "content"),
+    sort="date:desc",
+)
+
+summary = glpi.get_task_durations(
+    start_date="2026-01-01",
+    end_date="2026-01-31",
+    entity_name="Novahe",
+    return_task_details=True,
+)
+
+print(summary["total_duration"])
+print(summary["duration_by_user"])
+```
+
+`GlpiTask` keeps typed fields such as `ticket_id`, `user_id`, `duration`,
+`date`, and `entity`. Additional task payload keys remain available through
+`GlpiTask.extra_payload`.
+
+## Ticket Statistics And User Activity
+
+Public enums keep the GLPI numeric constants at the package root and can be
+used directly in filters.
+
+```python
+from glpi_python_client import GlpiPriority, GlpiTicketStatus, GlpiTicketType
+
+open_ticket_query = GlpiTicketStatus.NEW.rsql_equals("status")
+request_query = GlpiTicketType.REQUEST.rsql_equals("type")
+
+stats = glpi.get_ticket_statistics(
+    entity_name="Novahe",
+    start_date="2026-01-01",
+    end_date="2026-01-31",
+    extra_filter=f"{open_ticket_query};{request_query}",
+)
+
+activity = glpi.get_user_activity(
+    email="jane.doe@example.com",
+    start_date="2026-01-01",
+    end_date="2026-01-31",
+)
+
+print(stats["entities"])
+print(activity["users"])
+```
+
+The statistics output groups counts by entity, status, priority, and type. The
+activity output groups requester counts, technician counts, and nested task
+duration summaries by user.
+
+## Ticket Context
+
+Use `get_ticket_context()` when you need the core ticket together with the
+common timeline and document records in one public object.
+
+```python
+bundle = glpi.get_ticket_context("123")
+
+print(bundle.ticket.id)
+print(len(bundle.tasks), len(bundle.followups), len(bundle.solutions))
+print(len(bundle.documents))
+```
+
 ## Users and Locations
 
 ```python

docs/user_guide.rst

@@ -161,6 +161,117 @@ Replace ``_room_code`` and ``_asset_tag`` with the field names expected by your
 GLPI instance or plugin. The same ``extra_payload`` pattern works with the
 other public payload-backed models.
 
+Requested Ticket Fields Not Modeled Directly
+--------------------------------------------
+
+When you request extra ticket fields that do not map to typed
+:class:`glpi_python_client.GlpiTicket` attributes, the package preserves those
+values in ``ticket.extra_payload`` instead of dropping them.
+
+.. code-block:: python
+
+   tickets = glpi.search_ticket_records(
+       query='status.id=in=(1,2)',
+       fields=("resolution_date", "date_solve"),
+   )
+
+   first_ticket = tickets[0]
+   print(first_ticket.extra_payload["resolution_date"])
+   print(first_ticket.extra_payload["date_solve"])
+
+Entity Search
+-------------
+
+Use :meth:`glpi_python_client.GlpiClient.search_entities` when you need typed
+entity lookup from the public package root.
+
+.. code-block:: python
+
+   entities = glpi.search_entities(
+       rsql_filter='name=like=*novahe*',
+       limit=50,
+       start=0,
+   )
+
+   for entity in entities:
+       print(entity.entity_id, entity.name, entity.complete_name)
+
+Unmodeled entity payload keys remain available through
+:attr:`glpi_python_client.GlpiEntity.extra_payload`.
+
+Task Search and Duration Statistics
+-----------------------------------
+
+Use :meth:`glpi_python_client.GlpiClient.search_task_records` for global task
+searches and :meth:`glpi_python_client.GlpiClient.get_task_durations` when you
+need aggregated duration reports.
+
+.. code-block:: python
+
+   tasks = glpi.search_task_records(
+       query='date=ge=2026-01-01;date=le=2026-01-31',
+       fields=("id", "tickets_id", "users_id", "actiontime", "date", "content"),
+       sort="date:desc",
+   )
+
+   summary = glpi.get_task_durations(
+       start_date="2026-01-01",
+       end_date="2026-01-31",
+       entity_name="Novahe",
+       return_task_details=True,
+   )
+
+   print(summary["total_duration"])
+   print(summary["duration_by_user"])
+
+:class:`glpi_python_client.GlpiTask` keeps typed fields such as ``ticket_id``,
+``user_id``, ``duration``, ``date``, and ``entity``. Additional task payload
+keys remain available through ``extra_payload``.
+
+Ticket Statistics and User Activity
+-----------------------------------
+
+Public enums keep the common GLPI numeric constants at the package root and
+can be used directly when composing RSQL filters.
+
+.. code-block:: python
+
+   from glpi_python_client import GlpiTicketStatus, GlpiTicketType
+
+   open_ticket_query = GlpiTicketStatus.NEW.rsql_equals("status")
+   request_query = GlpiTicketType.REQUEST.rsql_equals("type")
+
+   stats = glpi.get_ticket_statistics(
+       entity_name="Novahe",
+       start_date="2026-01-01",
+       end_date="2026-01-31",
+       extra_filter=f"{open_ticket_query};{request_query}",
+   )
+
+   activity = glpi.get_user_activity(
+       email="jane.doe@example.com",
+       start_date="2026-01-01",
+       end_date="2026-01-31",
+   )
+
+   print(stats["entities"])
+   print(activity["users"])
+
+Ticket Context Bundles
+----------------------
+
+Use :meth:`glpi_python_client.GlpiClient.get_ticket_context` when one workflow
+needs the primary ticket together with the common timeline and document
+records.
+
+.. code-block:: python
+
+   bundle = glpi.get_ticket_context("123")
+
+   print(bundle.ticket.id)
+   print(len(bundle.tasks), len(bundle.followups), len(bundle.solutions))
+   print(len(bundle.documents))
+
 Utility Constructor
 -------------------