glpi-python-client 0.5.0__tar.gz → 0.6.0__tar.gz

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/.gitignore

@@ -33,7 +33,7 @@ CLAUDE.md
 docs/superpowers/*
 
 # Large generated GLPI API contract (kept locally, not tracked)
-docs/glpi_api_contract.json
+docs/api_contract/
 # Coverage data: rewritten by every test run (and by the venv .pth hook).
 .coverage
 .coverage.*

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.6.0 — 2026-10-01
+
+### Changed (breaking)
+
+- **Python 3.10 is no longer supported; 3.11 is the minimum.** The
+  `typing-extensions` and `tomli` backports it needed are dropped.
+- **Content conversion is rebuilt on three libraries: markdownify,
+  mdformat and cmark-gfm.** `from_transport` reads GLPI's HTML with
+  `markdownify`, and `mdformat` re-renders that Markdown from its syntax
+  tree, so it keeps only the escapes CommonMark needs. `to_transport`
+  renders through `cmark-gfm`, the GitHub reference implementation, in
+  place of python-markdown. A thin layer of glue sits on top. Measured on
+  346 real bodies sampled from a GLPI 11 instance:
+  - 322 display the same after a round trip, against 299 before;
+  - 344 read back as the same Markdown, against 240.
+
+  Of 205 realistic caller-written Markdown documents, all 205 survive
+  Markdown → HTML → Markdown with the same display.
+- **Markdown is rendered as CommonMark with GFM tables.** A newline is a
+  line break, as `nl2br` made it before. Raw HTML passes through.
+  Differences you may see in Markdown you write:
+  - a list or a table written straight after a line now starts a list or a
+    table, where python-markdown wanted a blank line first;
+  - lists nested by two or three spaces nest;
+  - `1)` starts a numbered list;
+  - `#Important`, with no space, is text rather than a heading;
+  - `*a **b** c*` keeps its bold;
+  - a backslash ending a line is a line break, so write `C:\Temp\` at the
+    end of a line as `` `C:\Temp\` ``;
+  - `<word>` is read as an HTML tag, so put a placeholder such as `<login>`
+    in backticks.
+- **`.content` is spelled as canonical CommonMark.** A line break reads
+  back as `\` and a newline, a nested list is indented by its bullet's
+  width, and a table comes back unpadded. Text that would otherwise read as
+  syntax is escaped: `__init__` reads `\_\_init\_\_`, and a `* point` line
+  reads `\* point`. Stored digests of `.content` change once.
+- **A plain-text body is literal text on the read path.** A value with no
+  HTML element used to come back verbatim and be rendered as Markdown. It is
+  now read as GLPI displays it, its lines as lines.
+  `GlpiContentConverter.from_transport` takes `plain_text_is_markdown`.
+  `True` is what the write models' validator passes: caller-authored
+  Markdown passes verbatim unless it starts with an HTML tag, so Markdown
+  carrying an inline `<br>` or `<kbd>` stays Markdown.
+- **Dependencies.**
+  - Added: `cmarkgfm>=2025.10` (compiled wheels for CPython 3.11–3.14 on
+    Linux, macOS and Windows), `mdformat>=0.7.22,<0.8`,
+    `mdformat-tables>=1.0` and `markdown-it-py>=3.0`.
+  - Dropped: `markdown`. python-markdown 3.11 had broken the previous
+    reader.
+  - Raised: `beautifulsoup4>=4.15`, which fixed the parser defect that
+    dropped the text after a `<br />` in a body that also held a bare
+    `<br>`. That removes the workaround.
+
+### Fixed
+
+- **Literal text came back as Markdown syntax.** These now read back as the
+  text a user typed:
+  - `\serveur\compta`, which had lost a backslash;
+  - `__init__` and `______`, which had become bold;
+  - a `-----` line under text, which had made a heading;
+  - `* point` and `> merci` lines, which had become a list and a quote;
+  - `[1]: https://...`, which had been consumed as a reference definition;
+  - a `|` in a table cell, which had dropped the rest of the row.
+- **A table nested in a table cell lost all its text.** That is the usual
+  layout of an e-mail signature. The inner table is now written as its
+  cells' text, its line breaks kept as `<br>`.
+- **Nested lists flattened on the first write.** Nested items, the text
+  after a nested list, and numbering, `start` included, survive.
+- `<script>`, `<style>` and `<title>` bodies no longer leak into the text.
+- A blank line inside a paragraph (`<br><br>`, or Outlook's
+  `<br>&nbsp;<br>`) is kept.
+- A label in bold right before a figure, as in `<b>Total:</b>12`, keeps its
+  bold.
+- A code fence keeps its language, and a `|` inside code in a table cell no
+  longer splits the row.
+- A long body converts in linear time, and a body nested deeper than the
+  stack is read as its text instead of raising.
+
+### Known limitations
+
+- A Markdown table needs a header row and the same number of cells in every
+  row. A header-less HTML table gains an empty header row, and a row that
+  spans the table gains empty cells.
+- Struck-through text is kept as raw `<s>`, since CommonMark has no
+  strikethrough.
+- Literal text that looks like syntax is sometimes escaped where
+  CommonMark would not need it, for example `5\*3` or `x \<= y`. It
+  displays as typed.
+
 ## 0.5.0 — 2026-09-08
 
 ### Fixed

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/CONTRIBUTING.md

@@ -38,7 +38,7 @@ python -m sphinx -W --keep-going -b html docs docs/_build/html
 
 ## GitHub Actions
 
-- `.github/workflows/ci.yml` runs tests for Python 3.10 through 3.14 on pull
+- `.github/workflows/ci.yml` runs tests for Python 3.11 through 3.14 on pull
   requests and pushes to `main`.
 - The same workflow runs `ruff`, `mypy`, and a warning-free Sphinx build on
   Python 3.12.
@@ -63,3 +63,19 @@ python -m sphinx -W --keep-going -b html docs docs/_build/html
   library core.
 - Add tests for payload serialization and response normalization when adding
   endpoints.
+
+### The GLPI OpenAPI contract
+
+The models under `glpi_python_client/models/api_schema/` mirror
+`components.schemas.*` from the GLPI High-Level REST API document,
+including which fields are `readOnly`. That document is not committed —
+it is ~14 MB and instance-specific. Fetch your instance's copy to the
+path the models cite:
+
+```bash
+curl -sk "<your GLPI base>/api.php/v2.3/doc.json" -o docs/api_contract/api.json
+```
+
+`docs/api_contract/` is gitignored. Nothing in CI checks the models
+against it, so when you add or change a model, diff it against the
+contract by hand.

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.5.0
+Version: 0.6.0
 Summary: A typed Python client for GLPI ITSM APIs.
 Project-URL: Homepage, https://github.com/baraline/glpi_python_client
 Project-URL: Documentation, https://glpi-python-client.readthedocs.io/en/latest/
@@ -15,7 +15,6 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -23,16 +22,18 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: beautifulsoup4>=4.12
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.15
+Requires-Dist: cmarkgfm>=2025.10
 Requires-Dist: httpx>=0.28
 Requires-Dist: lxml>=4.9
-Requires-Dist: markdown>=3.6
-Requires-Dist: markdownify>=0.13
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: markdownify>=1.2
+Requires-Dist: mdformat-tables>=1.0
+Requires-Dist: mdformat<0.8,>=0.7.22
 Requires-Dist: pydantic>=2.8
 Requires-Dist: sniffio>=1.3
 Requires-Dist: tenacity>=8.2
-Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
 Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
@@ -45,7 +46,6 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'dev'
 Requires-Dist: sphinx<8.2,>=7.2; extra == 'dev'
-Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
 Requires-Dist: twine>=5.1; extra == 'dev'
 Requires-Dist: unasync>=0.6; extra == 'dev'
 Requires-Dist: vulture>=2.11; extra == 'dev'
@@ -53,7 +53,6 @@ Provides-Extra: docs
 Requires-Dist: numpydoc>=1.8; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
 Requires-Dist: sphinx<8.2,>=7.2; extra == 'docs'
-Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'docs'
 Description-Content-Type: text/markdown
 
 # glpi-python-client
@@ -61,7 +60,7 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/baraline/glpi_python_client/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/baraline/glpi_python_client/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/baraline/glpi_python_client/branch/main/graph/badge.svg)](https://codecov.io/gh/baraline/glpi_python_client)
 [![License](https://img.shields.io/github/license/baraline/glpi_python_client)](LICENSE)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/baraline/glpi_python_client)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/baraline/glpi_python_client)
 [![Docs](https://readthedocs.org/projects/glpi-python-client/badge/?version=latest)](https://glpi-python-client.readthedocs.io/en/latest/)
 
 `glpi-python-client` is a typed Python client for the GLPI REST API.

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/baraline/glpi_python_client/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/baraline/glpi_python_client/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/baraline/glpi_python_client/branch/main/graph/badge.svg)](https://codecov.io/gh/baraline/glpi_python_client)
 [![License](https://img.shields.io/github/license/baraline/glpi_python_client)](LICENSE)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/baraline/glpi_python_client)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/baraline/glpi_python_client)
 [![Docs](https://readthedocs.org/projects/glpi-python-client/badge/?version=latest)](https://glpi-python-client.readthedocs.io/en/latest/)
 
 `glpi-python-client` is a typed Python client for the GLPI REST API.

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/docs/api_reference.rst

@@ -113,18 +113,19 @@ conversion happens, which buys two things: listing records costs nothing
 per body, and a body that cannot be converted no longer stops the rest of
 its page being read.
 
+The Markdown is CommonMark with GFM tables, rendered by cmark-gfm. It
+spells a body's text as literal text -- ``\_\_init\_\_``, ``\\\serveur``,
+``\# pas un titre`` -- so rendering it displays what GLPI displayed and
+reading that back gives the same Markdown. A write model keeps the caller's
+Markdown verbatim unless it starts with an HTML tag. See
+:ref:`content-conversion`.
+
 Very deeply nested HTML is the case worth knowing about.
 ``markdownify`` walks the document recursively and runs out of stack at
-around 494 levels of nesting. The converter does not try to predict
-that: it attempts the conversion and, if the walk does not fit, strips
-tags instead. It degrades, it never truncates, and it does not raise:
-every character the normal rendering would have produced still appears.
-What is lost is structure rather than words — link targets and image alt
-text, code fencing and ``<pre>`` indentation, ``&nbsp;`` alignment.
-Because the budget is the stack left when the conversion starts, the
-same body can convert from one call site and degrade from a deeper one.
-Anything else that goes wrong in either direction raises
-:class:`GlpiContentError`.
+a few hundred levels of nesting. The converter attempts the conversion
+and, if the walk does not fit, reads the body's text instead, a line per
+block: the words survive, the structure does not. Anything else that goes
+wrong in either direction raises :class:`GlpiContentError`.
 
 Because the conversion is cached on first read, a read model should be
 treated as immutable afterwards: assigning to ``content_html``, or
@@ -499,6 +500,121 @@ The companion mixin methods are exposed on :class:`GlpiClient` /
    :undoc-members:
    :show-inheritance:
 
+Computers
+---------
+
+.. autoclass:: GetComputer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostComputer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PatchComputer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DeleteComputer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Computer Contract Links
+-----------------------
+
+.. autoclass:: GetContractItem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostContractItem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PatchContractItem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DeleteContractItem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Contracts
+---------
+
+.. autoclass:: GetContract
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostContract
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PatchContract
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DeleteContract
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Contract Costs
+--------------
+
+.. autoclass:: GetContractCost
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostContractCost
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PatchContractCost
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DeleteContractCost
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Contract Types
+--------------
+
+.. autoclass:: GetContractType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostContractType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PatchContractType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DeleteContractType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Enums
 -----
 
@@ -547,6 +663,11 @@ Enums
    :undoc-members:
    :show-inheritance:
 
+.. autoclass:: GlpiContractRenewalType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Package Metadata
 ----------------
 

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/docs/conf.py

@@ -5,11 +5,7 @@ from __future__ import annotations
 from datetime import date
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
-
-try:
-    from tomllib import loads as toml_loads
-except ModuleNotFoundError:
-    from tomli import loads as toml_loads
+from tomllib import loads as toml_loads
 
 
 def _read_project_version() -> str:

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/docs/installation.rst

@@ -4,7 +4,7 @@ Installation
 Requirements
 ------------
 
-``glpi-python-client`` supports Python 3.10 and newer. Runtime dependencies are installed
+``glpi-python-client`` supports Python 3.11 and newer. Runtime dependencies are installed
 from the package metadata and include ``httpx``, ``tenacity``,
 ``beautifulsoup4``, ``lxml``, and ``pydantic``.
 

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/docs/publishing_rtd.rst

@@ -92,7 +92,7 @@ GitHub Actions and Read the Docs
 The repository ships with two GitHub Actions workflows:
 
 * ``.github/workflows/ci.yml`` runs on pull requests and pushes to ``main``.
-   It executes ``pytest`` on Python 3.10 through 3.14, then runs ``ruff``,
+   It executes ``pytest`` on Python 3.11 through 3.14, then runs ``ruff``,
    ``mypy``, and the Sphinx build on Python 3.12.
 * ``.github/workflows/release.yml`` runs on published GitHub releases. It
    repeats the quality checks, builds the source and wheel distributions,

{glpi_python_client-0.5.0 → glpi_python_client-0.6.0}/docs/user_guide.rst

@@ -38,7 +38,7 @@ The guide is split into the following sections:
    throwaway GLPI instance to follow along.
 4. **GLPI API interface** — the contract-aligned helpers that map
    one-to-one to GLPI v2 endpoints (tickets, timeline, team members,
-   users, locations, entities, documents).
+   users, locations, entities, documents, computers, contracts).
 5. **Added functionalities** — helpers built on top of the API mixins:
     the ``Fields`` plugin custom-field helpers, the aggregated ticket
     context view, and the reporting helpers.
@@ -580,6 +580,211 @@ Example output::
 the client (``v1_base_url`` and ``v1_user_token``) because the GLPI v2
 contract does not advertise a binary upload endpoint.
 
+Assets
+~~~~~~
+
+The asset mixins map to ``/Assets/*``. GLPI models roughly two dozen
+asset itemtypes (computers, monitors, printers, network equipment, and
+so on), and this client currently implements only ``Computer`` -- there
+is no ``search_monitors`` or ``get_printer``. Treat ``Computer`` as the
+one supported asset type rather than a stand-in for the rest of the
+family.
+
+``search_ / get_ / create_ / update_ / delete_`` follow the same shape
+as the other resources, with ``iter_search_computers`` for streaming
+pagination and the same ``rsql_filter`` / ``limit`` / ``start`` /
+``sort`` arguments as ``search_tickets``:
+
+.. code-block:: python
+
+   from glpi_python_client import PatchComputer, PostComputer
+
+   computer_id = client.create_computer(
+       PostComputer(name="ws-1042", serial="PF3KL9QJ")
+   )
+   client.update_computer(
+       computer_id, PatchComputer(comment="Reimaged for the finance team")
+   )
+   computer = client.get_computer(computer_id)
+   print(computer.id, computer.name, computer.serial)
+
+   results = client.search_computers("name==ws-1042", limit=5)
+   for c in results:
+       print(c.id, c.name)
+
+Example output::
+
+   1042 ws-1042 PF3KL9QJ
+   1042 ws-1042
+
+Linking a computer to a contract
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A computer's coverage contracts are tracked as links under
+``/Assets/Computer/{id}/Contract``, exposed as
+``list_computer_contracts``, ``get_computer_contract``,
+``link_computer_contract``, ``update_computer_contract``, and
+``unlink_computer_contract``:
+
+.. code-block:: python
+
+   from glpi_python_client import IdNameRef, PostContract, PostContractItem
+
+   contract_id = client.create_contract(PostContract(name="Dell ProSupport 2026"))
+
+   link_id = client.link_computer_contract(
+       computer_id, PostContractItem(contract=IdNameRef(id=contract_id))
+   )
+   for link in client.list_computer_contracts(computer_id):
+       print(link.id, link.itemtype, link.items_id)
+
+   client.unlink_computer_contract(computer_id, link_id, force=True)
+
+Example output::
+
+   17 Computer 1042
+
+The underlying ``Contract_Item`` GLPI resource is shared by every asset
+type, so ``PostContractItem`` and ``PatchContractItem`` both carry an
+``itemtype`` field typed as a free string rather than an enum --
+nothing stops a caller from writing ``"Computre"``. Because of that,
+``link_computer_contract`` and ``update_computer_contract`` ignore
+whatever ``itemtype`` and ``items_id`` are set on the body passed in
+and set both fields themselves from ``computer_id``. Pass only
+``contract`` (and ``comment``, if the contract ever adds one); a typo
+in the two identifying fields would otherwise attach the link to the
+wrong kind of object with no error from either side.
+
+Contracts
+~~~~~~~~~
+
+The contract mixin maps to ``/Management/Contract`` with the usual
+``search_ / get_ / create_ / update_ / delete_`` shape and
+``iter_search_contracts`` for streaming pagination:
+
+.. code-block:: python
+
+   from glpi_python_client import PatchContract, PostContract
+
+   contract_id = client.create_contract(
+       PostContract(name="Dell ProSupport 2026", number="CTR-2026-001")
+   )
+   client.update_contract(
+       contract_id, PatchContract(comment="Renewed for another year")
+   )
+   contract = client.get_contract(contract_id)
+   print(contract.id, contract.name, contract.date_begin)
+
+   results = client.search_contracts("name==Dell ProSupport 2026", limit=5)
+   for c in results:
+       print(c.id, c.name)
+
+Example output::
+
+   501 Dell ProSupport 2026 2026-01-15
+   501 Dell ProSupport 2026
+
+.. warning::
+
+   ``date_begin`` on :class:`~glpi_python_client.GetContract` and
+   :class:`~glpi_python_client.PostContract` is a plain
+   :class:`datetime.date`, not a :class:`~datetime.datetime`. The GLPI
+   contract declares this field with ``format: date`` -- a contract has
+   no time-of-day for its start. That choice is load-bearing, not
+   cosmetic: the server-clock conversion in ``models/_base.py`` that
+   rewrites timestamps into the configured ``server_timezone`` only
+   touches values that are instances of :class:`datetime.datetime`, and
+   a plain :class:`~datetime.date` is not one, so ``date_begin`` never
+   enters that conversion. Had it been modelled as ``datetime`` it would
+   have been eligible, and converting a midnight, offset-naive value
+   between timezones can roll it onto the previous or next calendar
+   day. Note the asymmetry: ``date_begin`` and ``date_end`` on
+   ``ContractCost`` (below) *are* ``datetime`` fields, because the
+   contract declares those two with ``format: date-time``. That
+   difference comes from the GLPI contract itself and is not an
+   inconsistency to reconcile.
+
+Contract costs
+^^^^^^^^^^^^^^
+
+Cost lines live under ``/Management/Contract/{id}/Cost`` as a genuine
+sub-resource with their own create, update, and delete endpoints:
+``list_contract_costs``, ``get_contract_cost``,
+``create_contract_cost``, ``update_contract_cost``, and
+``delete_contract_cost``.
+
+.. code-block:: python
+
+   from glpi_python_client import PatchContractCost, PostContractCost
+
+   cost_id = client.create_contract_cost(
+       contract_id, PostContractCost(name="Year 1", cost=4200.0)
+   )
+   client.update_contract_cost(
+       contract_id, cost_id, PatchContractCost(comment="Paid on invoice #88")
+   )
+   cost = client.get_contract_cost(contract_id, cost_id)
+   print(cost.id, cost.name, cost.cost)
+
+   print(len(client.list_contract_costs(contract_id)))
+
+   client.delete_contract_cost(contract_id, cost_id, force=True)
+
+Example output::
+
+   9 Year 1 4200.0
+   1
+
+.. note::
+
+   ``costs`` on :class:`~glpi_python_client.GetContract` is read-only:
+   it comes back populated with references to the contract's cost
+   lines, but the field does not exist at all on ``PostContract`` or
+   ``PatchContract``. Write cost lines through
+   ``create_contract_cost``, ``update_contract_cost``, and
+   ``delete_contract_cost`` instead of trying to assign ``costs`` on
+   the parent contract.
+
+Contract types
+^^^^^^^^^^^^^^
+
+``/Dropdowns/ContractType`` is a plain dropdown: ``search_ / get_ /
+create_ / update_ / delete_`` plus ``iter_search_contract_types``.
+Unlike ``search_computers`` and ``search_contracts``, the contract-type
+search helpers do not accept a ``sort`` argument.
+
+.. code-block:: python
+
+   from glpi_python_client import PostContractType
+
+   type_id = client.create_contract_type(PostContractType(name="Maintenance"))
+   contract_type = client.get_contract_type(type_id)
+   print(contract_type.id, contract_type.name)
+
+Example output::
+
+   6 Maintenance
+
+Assign the type -- and a renewal behaviour -- through the parent
+contract:
+
+.. code-block:: python
+
+   from glpi_python_client import GlpiContractRenewalType, IdNameRef, PatchContract
+
+   client.update_contract(
+       contract_id,
+       PatchContract(
+           type=IdNameRef(id=type_id),
+           renewal_type=GlpiContractRenewalType.TACIT,
+       ),
+   )
+
+:class:`glpi_python_client.GlpiContractRenewalType` mirrors the three
+values GLPI documents for ``Contract.renewal_type``: ``NONE`` (no
+renewal), ``TACIT`` (automatic renewal), and ``EXPLICIT`` (manual
+renewal).
+
 Knowledge base
 ~~~~~~~~~~~~~~
 
@@ -685,8 +890,9 @@ the package root for easy use in RSQL filters:
 :class:`glpi_python_client.GlpiTaskState`,
 :class:`glpi_python_client.GlpiSolutionStatus`,
 :class:`glpi_python_client.GlpiTimelinePosition`,
-:class:`glpi_python_client.GlpiUserAuthType`, and
-:class:`glpi_python_client.GlpiGlobalValidation`.
+:class:`glpi_python_client.GlpiUserAuthType`,
+:class:`glpi_python_client.GlpiGlobalValidation`, and
+:class:`glpi_python_client.GlpiContractRenewalType`.
 
 .. code-block:: python
 
@@ -1552,6 +1758,36 @@ The whole page is built in one pass, so a single unconvertible record used
 to make its page-mates unreadable too. The failure is now scoped to the
 record whose body you actually read.
 
+The Markdown is CommonMark with GFM tables. Rendering it -- as the package
+does on the way back to GLPI, with cmark-gfm -- displays what GLPI
+displayed, and reading that rendering back gives the same Markdown. Text in
+a body is literal: Markdown has one spelling for ``__init__`` typed by a
+user and for bold ``init``, so text that would read as syntax is escaped:
+
+.. code-block:: python
+
+   from glpi_python_client.content import GlpiContentConverter
+
+   GlpiContentConverter.from_transport(
+       r"<p>Voir __init__ et \\serveur\compta</p><p># pas un titre</p>"
+   )
+   # Voir \_\_init\_\_ et \\\serveur\compta
+   #
+   # \# pas un titre
+
+Ordinary prose stays as typed: ``fichier_de_test_v2.xlsx``, ``C:\Temp``,
+``R&D``, a ``#`` mid-sentence. The spelling is canonical: a line break reads
+back as ``\`` and a newline, a nested list is indented by its bullet's width,
+and a table comes back unpadded. A body with no HTML element is plain text
+and is read as GLPI shows it, its lines as lines.
+
+Writing, your Markdown is rendered by cmark-gfm. A newline is a line break,
+GFM tables work, and raw HTML passes through, so put a placeholder such as
+``<login>`` in backticks. A write model keeps your Markdown verbatim unless
+it starts with an HTML tag, in which case it is read as HTML. A Markdown
+table needs a header row, so a header-less HTML table reads back with an
+empty one, and struck-through text stays as raw ``<s>``.
+
 .. note::
 
    Deeply nested HTML is the case worth knowing about. The HTML-to-Markdown