aiocospend 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ .venv/
5
+ venv/
6
+ .pytest_cache/
7
+ .ruff_cache/
8
+ *.egg-info/
9
+ dist/
10
+ build/
11
+
12
+ # Node
13
+ node_modules/
14
+
15
+ # Carte compilée : produite par la CI à la publication
16
+ custom_components/cospend/www/cospend-card.js
17
+ custom_components/cospend/www/cospend-card.js.map
18
+
19
+ # Local
20
+ .env
21
+ .vscode/
22
+ .idea/
@@ -0,0 +1,83 @@
1
+ Metadata-Version: 2.5
2
+ Name: aiocospend
3
+ Version: 0.2.0
4
+ Summary: Client asynchrone pour l'API OCS de Nextcloud Cospend
5
+ Project-URL: Homepage, https://github.com/SpaRtzZii/cospend-ha
6
+ Project-URL: Issues, https://github.com/SpaRtzZii/cospend-ha/issues
7
+ License-Expression: GPL-3.0-only
8
+ Requires-Python: >=3.13
9
+ Requires-Dist: aiohttp>=3.9
10
+ Provides-Extra: test
11
+ Requires-Dist: pytest; extra == 'test'
12
+ Requires-Dist: pytest-asyncio; extra == 'test'
13
+ Description-Content-Type: text/markdown
14
+
15
+ # aiocospend
16
+
17
+ Client asynchrone (aiohttp) pour l'API OCS de [Nextcloud Cospend](https://github.com/julien-nc/cospend-nc).
18
+ Fait partie du dépôt [cospend-ha](https://github.com/SpaRtzZii/cospend-ha). Version 0.2.0.
19
+
20
+ ```python
21
+ import time
22
+
23
+ import aiohttp
24
+ from aiocospend import CospendClient
25
+
26
+ async with aiohttp.ClientSession() as session:
27
+ client = CospendClient(
28
+ session, "https://cloud.exemple.org", "utilisateur", "mot-de-passe-d-application"
29
+ )
30
+ await client.check_connection() # adresse, identifiants, version de Cospend (>= 1.6.1)
31
+
32
+ project = (await client.get_projects())[0] # membres, catégories, soldes inclus
33
+ page = await client.get_bills(project.id) # page.timestamp = curseur du prochain last_changed
34
+ delta = await client.get_bills(project.id, last_changed=page.timestamp)
35
+
36
+ bill_id = await client.create_bill(
37
+ project.id,
38
+ what="Courses",
39
+ amount=42.5,
40
+ payer_id=project.members[0].id,
41
+ payed_for=[m.id for m in project.members],
42
+ timestamp=int(time.time()),
43
+ date=time.strftime("%Y-%m-%d"),
44
+ )
45
+ await client.update_bill(project.id, bill_id, amount=45) # modification partielle
46
+ await client.delete_bill(project.id, bill_id) # corbeille
47
+ ```
48
+
49
+ ## Synchronisation incrémentale
50
+
51
+ ```python
52
+ from aiocospend import ProjectBills
53
+
54
+ store = ProjectBills(project.id)
55
+ changes = await store.sync(
56
+ client, full_sync_max_age=24 * 3600
57
+ ) # complète au besoin, sinon incrémentale
58
+ for bill in changes.added:
59
+ ... # changes.updated, changes.deleted ; changes.is_initial = première lecture
60
+ ```
61
+
62
+ ## À savoir (relevé sur Cospend 4.3.0)
63
+
64
+ - Les écritures sont envoyées en formulaire, avec tous les champs à la création (comme Cowspent).
65
+ - **Supprimer une dépense déjà en corbeille la supprime définitivement.** Le client ne rejoue jamais
66
+ une suppression : relisez l'état de la dépense avant de réessayer.
67
+ - La lecture incrémentale (`last_changed`) ne renvoie pas les dépenses mises en corbeille ; on les
68
+ repère par leur absence de `all_bill_ids`.
69
+ - Les montants renvoyés par le serveur (statistiques, remboursements) ne sont pas arrondis.
70
+
71
+ ## Tests
72
+
73
+ ```bash
74
+ pip install -e ".[test]"
75
+ pytest tests # faux serveur Cospend local, sans réseau externe
76
+ ```
77
+
78
+ ## Publication sur PyPI (mainteneur)
79
+
80
+ Le paquet est publié par le workflow manuel `publish-aiocospend.yml`, sans mot de passe, par
81
+ « Trusted Publisher » : sur pypi.org, ajouter un *pending publisher* (propriétaire `SpaRtzZii`,
82
+ dépôt `cospend-ha`, workflow `publish-aiocospend.yml`, environnement `pypi`), créer l'environnement
83
+ `pypi` dans les réglages du dépôt GitHub, puis lancer le workflow depuis l'onglet Actions.
@@ -0,0 +1,69 @@
1
+ # aiocospend
2
+
3
+ Client asynchrone (aiohttp) pour l'API OCS de [Nextcloud Cospend](https://github.com/julien-nc/cospend-nc).
4
+ Fait partie du dépôt [cospend-ha](https://github.com/SpaRtzZii/cospend-ha). Version 0.2.0.
5
+
6
+ ```python
7
+ import time
8
+
9
+ import aiohttp
10
+ from aiocospend import CospendClient
11
+
12
+ async with aiohttp.ClientSession() as session:
13
+ client = CospendClient(
14
+ session, "https://cloud.exemple.org", "utilisateur", "mot-de-passe-d-application"
15
+ )
16
+ await client.check_connection() # adresse, identifiants, version de Cospend (>= 1.6.1)
17
+
18
+ project = (await client.get_projects())[0] # membres, catégories, soldes inclus
19
+ page = await client.get_bills(project.id) # page.timestamp = curseur du prochain last_changed
20
+ delta = await client.get_bills(project.id, last_changed=page.timestamp)
21
+
22
+ bill_id = await client.create_bill(
23
+ project.id,
24
+ what="Courses",
25
+ amount=42.5,
26
+ payer_id=project.members[0].id,
27
+ payed_for=[m.id for m in project.members],
28
+ timestamp=int(time.time()),
29
+ date=time.strftime("%Y-%m-%d"),
30
+ )
31
+ await client.update_bill(project.id, bill_id, amount=45) # modification partielle
32
+ await client.delete_bill(project.id, bill_id) # corbeille
33
+ ```
34
+
35
+ ## Synchronisation incrémentale
36
+
37
+ ```python
38
+ from aiocospend import ProjectBills
39
+
40
+ store = ProjectBills(project.id)
41
+ changes = await store.sync(
42
+ client, full_sync_max_age=24 * 3600
43
+ ) # complète au besoin, sinon incrémentale
44
+ for bill in changes.added:
45
+ ... # changes.updated, changes.deleted ; changes.is_initial = première lecture
46
+ ```
47
+
48
+ ## À savoir (relevé sur Cospend 4.3.0)
49
+
50
+ - Les écritures sont envoyées en formulaire, avec tous les champs à la création (comme Cowspent).
51
+ - **Supprimer une dépense déjà en corbeille la supprime définitivement.** Le client ne rejoue jamais
52
+ une suppression : relisez l'état de la dépense avant de réessayer.
53
+ - La lecture incrémentale (`last_changed`) ne renvoie pas les dépenses mises en corbeille ; on les
54
+ repère par leur absence de `all_bill_ids`.
55
+ - Les montants renvoyés par le serveur (statistiques, remboursements) ne sont pas arrondis.
56
+
57
+ ## Tests
58
+
59
+ ```bash
60
+ pip install -e ".[test]"
61
+ pytest tests # faux serveur Cospend local, sans réseau externe
62
+ ```
63
+
64
+ ## Publication sur PyPI (mainteneur)
65
+
66
+ Le paquet est publié par le workflow manuel `publish-aiocospend.yml`, sans mot de passe, par
67
+ « Trusted Publisher » : sur pypi.org, ajouter un *pending publisher* (propriétaire `SpaRtzZii`,
68
+ dépôt `cospend-ha`, workflow `publish-aiocospend.yml`, environnement `pypi`), créer l'environnement
69
+ `pypi` dans les réglages du dépôt GitHub, puis lancer le workflow depuis l'onglet Actions.
@@ -0,0 +1,22 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "aiocospend"
7
+ version = "0.2.0"
8
+ description = "Client asynchrone pour l'API OCS de Nextcloud Cospend"
9
+ readme = "README.md"
10
+ requires-python = ">=3.13"
11
+ license = "GPL-3.0-only"
12
+ dependencies = ["aiohttp>=3.9"]
13
+
14
+ [project.optional-dependencies]
15
+ test = ["pytest", "pytest-asyncio"]
16
+
17
+ [project.urls]
18
+ Homepage = "https://github.com/SpaRtzZii/cospend-ha"
19
+ Issues = "https://github.com/SpaRtzZii/cospend-ha/issues"
20
+
21
+ [tool.hatch.build.targets.wheel]
22
+ packages = ["src/aiocospend"]
@@ -0,0 +1,74 @@
1
+ """Client asynchrone pour l'API OCS de Nextcloud Cospend."""
2
+
3
+ from .client import CospendClient
4
+ from .const import MIN_COSPEND_VERSION
5
+ from .exceptions import (
6
+ CospendAuthenticationError,
7
+ CospendBadRequestError,
8
+ CospendConnectionError,
9
+ CospendError,
10
+ CospendForbiddenError,
11
+ CospendMaintenanceError,
12
+ CospendNotFoundError,
13
+ CospendResponseError,
14
+ CospendServerError,
15
+ CospendSSLError,
16
+ CospendVersionError,
17
+ )
18
+ from .models import (
19
+ Bill,
20
+ BillsPage,
21
+ Category,
22
+ Currency,
23
+ Member,
24
+ MemberStats,
25
+ Ower,
26
+ PaymentMode,
27
+ Project,
28
+ ProjectStatistics,
29
+ ServerInfo,
30
+ Settlement,
31
+ Share,
32
+ Transaction,
33
+ )
34
+ from .sync import BillChanges, ProjectBills
35
+ from .utils import compare_versions, format_amount, normalize_url, parse_version
36
+
37
+ __version__ = "0.2.0"
38
+
39
+ __all__ = [
40
+ "MIN_COSPEND_VERSION",
41
+ "Bill",
42
+ "BillChanges",
43
+ "BillsPage",
44
+ "Category",
45
+ "CospendAuthenticationError",
46
+ "CospendBadRequestError",
47
+ "CospendClient",
48
+ "CospendConnectionError",
49
+ "CospendError",
50
+ "CospendForbiddenError",
51
+ "CospendMaintenanceError",
52
+ "CospendNotFoundError",
53
+ "CospendResponseError",
54
+ "CospendSSLError",
55
+ "CospendServerError",
56
+ "CospendVersionError",
57
+ "Currency",
58
+ "Member",
59
+ "MemberStats",
60
+ "Ower",
61
+ "PaymentMode",
62
+ "Project",
63
+ "ProjectBills",
64
+ "ProjectStatistics",
65
+ "ServerInfo",
66
+ "Settlement",
67
+ "Share",
68
+ "Transaction",
69
+ "__version__",
70
+ "compare_versions",
71
+ "format_amount",
72
+ "normalize_url",
73
+ "parse_version",
74
+ ]