Pylan is a Python library that simulates the impact of scheduled events over time. You can install the Python library using PyPi with the following command:
```
pip install pylan-lib
```
This code snippet shows some basic functionality when doing simulations.
```python
from pylan import AddGrow, Item, Subtract
savings = Item(start_value=100)
dividends = AddGrow("90d", 100, "1y", 1.1) # the dividend will grow with 10% each year
growing_salary = AddGrow("1m", 2500, "1y", 1.2, offset_start="24d") # every month 24th
mortgage = Subtract("0 0 2 * *", 1500) # cron support
savings.add_patterns([growing_salary, dividends, mortgage])
result = savings.run("2024-1-1", "2028-1-1")
x, y = result.plot_axes()
```
There are 2 important classes in this library: Item and Pattern. A pattern is an abstract base class, with multiple implementations. These implementations resemble a time based pattern (e.g. add 10 every month, yearly inflation, etc). The Item is something that patterns can be added to, like a savings account.
---
## Class: Item
An item that you can apply patterns to and simulate over time. Optionally, you can
set a start value.
```python
>>> savings = Item(start_value=100)
```
#### Item.add_pattern(self, pattern: Pattern) -> None:
Add a pattern object to this item.
```python
>>> test = Add(["2024-1-4", "2024-2-1"], 1)
>>> savings = Item(start_value=100)
>>> savings.add_pattern(test)
```
#### Item.add_patterns(self, patterns: list[Pattern]) -> None:
Adds a list of patterns object to this item.
```python
>>> gains = Multiply("4m", 1)
>>> adds = Multiply("2d", 1)
>>> savings = Item(start_value=100)
>>> savings.add_patterns([gains, adds])
```
#### Item.run(self, start: datetime | str, end: datetime | str) -> list:
Runs the provided patterns between the start and end date. Creates a result
object with all the iterations per day/month/etc.
```python
>>> savings = Item(start_value=100)
>>> savings.add_patterns([gains, adds])
>>> savings.run("2024-1-1", "2025-1-1")
```
#### Item.until(self, stop_value: float) -> timedelta:
Runs the provided patterns until a stop value is reached. Returns the timedelta
needed to reach the stop value. NOTE: Don't use offset with a start date here.
```python
>>> savings = Item(start_value=100)
>>> savings.add_patterns([gains, adds])
>>> savings.until(200) # returns timedelta
```
---
## Class: Result
Outputted by an item run. Result of a simulation between start and end date. Has the
schedule and values as attributes (which are both lists).
```python
>>> result = savings.run("2024-1-1", "2024-3-1")
>>> x, y = result.plot_axes() # can be used for matplotlib
>>> result.final # last value
>>> result.to_csv("test.csv")
```
#### Result.__str__(self) -> str:
String format of result is a column oriented table with dates and values.
#### Result.__getitem__(self, key: str | datetime) -> float | int:
Get a result by the date using a dict key.
```python
>>> print(result["2024-5-5"])
```
#### Result.final(self):
Returns the result on the last day of the simulation.
```python
>>> result = savings.run("2024-1-1", "2024-3-1")
>>> result.final
```
#### Result.plot_axes(self, categorical_x_axis: bool = False) -> tuple[list, list]:
Returns x, y axes of the simulated run. X axis are dates and Y axis are values.
```python
>>> result = savings.run("2024-1-1", "2024-3-1")
>>> x, y = result.plot_axes() # can be used for matplotlib
```
#### Result.to_csv(self, filename: str, sep: str = ";") -> None:
Exports the result to a csv file. Row oriented.
```python
>>> result = savings.run("2024-1-1", "2024-3-1")
>>> result.to_csv("test.csv")
```
---
## Class: Pattern
Pattern is an abstract base class with the following implementations:
- Add(schedule, value)
- Subtract(schedule, value)
- Multiply(schedule, value)
- Divide(schedule, value)
- AddGrow(schedule for addition, addition value, schedule for multiplication, multiply value):
Adds a value that can be {de,in}creased over time based on another schedule.
```python
>>> dividends = AddGrow("90d", 100, "1y", 1.1)
>>> growing_salary = AddGrow("1m", 2500, "1y", 1.2, offset_start="24d")
>>> mortgage = Subtract("0 0 2 * *", 1500) # cron support
>>> inflation = Divide(["2025-1-1", "2026-1-1", "2027-1-1"], 1.08)
```
#### Pattern.apply(self) -> None:
Applies the pattern to the item provided as a parameter. Implemented in the
specific classes.
#### Pattern.scheduled(self, current: datetime) -> bool:
Returns true if pattern is scheduled on the provided date.
---
## Schedule
Passed to patterns as a parameter. Is converted to a list of datetime objects. Accepts multiple formats.
#### Cron schedules
For example, "0 0 2 * *" runs on the second day of each month.
#### Timedelta strings
Combination of a count and timedelta. For example, 2d (every 2 days) 3m (every 3 months). Currently supports: years (y), months (m), weeks (w), days (d).
#### Timedelta lists
Same as timedelta, but then alternates between the schedules. For example, ["2d", "5d"] will be triggered after 2 days, then after 5 days, then after 2 days, etc...
#### Datetime lists
A list of datetime objects or str that resemble datetime objects. For example, ["2024-1-1", "2025-1-1"].
> **_NOTE:_** The date format in pylan is yyyy-mm-dd. Currently this is not configurable.
Raw data
{
"_id": null,
"home_page": "https://github.com/TimoKats/pylan",
"name": "pylan-lib",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Timo Kats",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f3/fb/ef1aec3c55ecc346d370fdfd1ed4e6729bea61183b8c44054322ae92d2b4/pylan_lib-0.1.1.tar.gz",
"platform": null,
"description": "Pylan is a Python library that simulates the impact of scheduled events over time. You can install the Python library using PyPi with the following command:\n\n```\npip install pylan-lib\n```\n\nThis code snippet shows some basic functionality when doing simulations.\n\n```python\nfrom pylan import AddGrow, Item, Subtract\n\nsavings = Item(start_value=100)\ndividends = AddGrow(\"90d\", 100, \"1y\", 1.1) # the dividend will grow with 10% each year\ngrowing_salary = AddGrow(\"1m\", 2500, \"1y\", 1.2, offset_start=\"24d\") # every month 24th\nmortgage = Subtract(\"0 0 2 * *\", 1500) # cron support\n\nsavings.add_patterns([growing_salary, dividends, mortgage])\nresult = savings.run(\"2024-1-1\", \"2028-1-1\")\n\nx, y = result.plot_axes()\n\n```\n\nThere are 2 important classes in this library: Item and Pattern. A pattern is an abstract base class, with multiple implementations. These implementations resemble a time based pattern (e.g. add 10 every month, yearly inflation, etc). The Item is something that patterns can be added to, like a savings account.\n\n\n\n---\n## Class: Item\n\nAn item that you can apply patterns to and simulate over time. Optionally, you can\nset a start value.\n\n```python\n>>> savings = Item(start_value=100)\n```\n\n#### Item.add_pattern(self, pattern: Pattern) -> None:\n\n\nAdd a pattern object to this item.\n\n```python\n>>> test = Add([\"2024-1-4\", \"2024-2-1\"], 1)\n>>> savings = Item(start_value=100)\n>>> savings.add_pattern(test)\n```\n\n#### Item.add_patterns(self, patterns: list[Pattern]) -> None:\n\n\nAdds a list of patterns object to this item.\n\n```python\n>>> gains = Multiply(\"4m\", 1)\n>>> adds = Multiply(\"2d\", 1)\n>>> savings = Item(start_value=100)\n>>> savings.add_patterns([gains, adds])\n```\n\n#### Item.run(self, start: datetime | str, end: datetime | str) -> list:\n\n\nRuns the provided patterns between the start and end date. Creates a result\nobject with all the iterations per day/month/etc.\n\n```python\n>>> savings = Item(start_value=100)\n>>> savings.add_patterns([gains, adds])\n>>> savings.run(\"2024-1-1\", \"2025-1-1\")\n```\n\n#### Item.until(self, stop_value: float) -> timedelta:\n\n\nRuns the provided patterns until a stop value is reached. Returns the timedelta\nneeded to reach the stop value. NOTE: Don't use offset with a start date here.\n\n```python\n>>> savings = Item(start_value=100)\n>>> savings.add_patterns([gains, adds])\n>>> savings.until(200) # returns timedelta\n```\n\n\n---\n## Class: Result\n\nOutputted by an item run. Result of a simulation between start and end date. Has the\nschedule and values as attributes (which are both lists).\n\n```python\n>>> result = savings.run(\"2024-1-1\", \"2024-3-1\")\n>>> x, y = result.plot_axes() # can be used for matplotlib\n>>> result.final # last value\n>>> result.to_csv(\"test.csv\")\n```\n\n#### Result.__str__(self) -> str:\n\n\nString format of result is a column oriented table with dates and values.\n\n#### Result.__getitem__(self, key: str | datetime) -> float | int:\n\n\nGet a result by the date using a dict key.\n\n```python\n>>> print(result[\"2024-5-5\"])\n```\n\n#### Result.final(self):\n\n\nReturns the result on the last day of the simulation.\n\n```python\n>>> result = savings.run(\"2024-1-1\", \"2024-3-1\")\n>>> result.final\n```\n\n#### Result.plot_axes(self, categorical_x_axis: bool = False) -> tuple[list, list]:\n\n\nReturns x, y axes of the simulated run. X axis are dates and Y axis are values.\n\n```python\n>>> result = savings.run(\"2024-1-1\", \"2024-3-1\")\n>>> x, y = result.plot_axes() # can be used for matplotlib\n```\n\n#### Result.to_csv(self, filename: str, sep: str = \";\") -> None:\n\n\nExports the result to a csv file. Row oriented.\n\n```python\n>>> result = savings.run(\"2024-1-1\", \"2024-3-1\")\n>>> result.to_csv(\"test.csv\")\n```\n\n\n---\n## Class: Pattern\n\n\nPattern is an abstract base class with the following implementations:\n- Add(schedule, value)\n- Subtract(schedule, value)\n- Multiply(schedule, value)\n- Divide(schedule, value)\n- AddGrow(schedule for addition, addition value, schedule for multiplication, multiply value):\n Adds a value that can be {de,in}creased over time based on another schedule.\n\n```python\n>>> dividends = AddGrow(\"90d\", 100, \"1y\", 1.1)\n>>> growing_salary = AddGrow(\"1m\", 2500, \"1y\", 1.2, offset_start=\"24d\")\n>>> mortgage = Subtract(\"0 0 2 * *\", 1500) # cron support\n>>> inflation = Divide([\"2025-1-1\", \"2026-1-1\", \"2027-1-1\"], 1.08)\n```\n\n#### Pattern.apply(self) -> None:\n\n\nApplies the pattern to the item provided as a parameter. Implemented in the\nspecific classes.\n\n#### Pattern.scheduled(self, current: datetime) -> bool:\n\n\nReturns true if pattern is scheduled on the provided date.\n\n\n---\n\n## Schedule\n\nPassed to patterns as a parameter. Is converted to a list of datetime objects. Accepts multiple formats.\n\n#### Cron schedules\nFor example, \"0 0 2 * *\" runs on the second day of each month.\n\n#### Timedelta strings\nCombination of a count and timedelta. For example, 2d (every 2 days) 3m (every 3 months). Currently supports: years (y), months (m), weeks (w), days (d).\n\n#### Timedelta lists\nSame as timedelta, but then alternates between the schedules. For example, [\"2d\", \"5d\"] will be triggered after 2 days, then after 5 days, then after 2 days, etc...\n\n#### Datetime lists\nA list of datetime objects or str that resemble datetime objects. For example, [\"2024-1-1\", \"2025-1-1\"].\n\n> **_NOTE:_** The date format in pylan is yyyy-mm-dd. Currently this is not configurable.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for time based planning.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/TimoKats/pylan"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "807f86b598d23ab3d6ed243b0b39367596a6fedb6ff78b1986bb0f03a3323947",
"md5": "bfae4611566f69982dc2af2abed82f4d",
"sha256": "4e3ee6a8760326536daaad1a6cee1158709418306f5c2bdc5da2d300ffd13477"
},
"downloads": -1,
"filename": "pylan_lib-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfae4611566f69982dc2af2abed82f4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11248,
"upload_time": "2025-03-01T20:00:46",
"upload_time_iso_8601": "2025-03-01T20:00:46.152502Z",
"url": "https://files.pythonhosted.org/packages/80/7f/86b598d23ab3d6ed243b0b39367596a6fedb6ff78b1986bb0f03a3323947/pylan_lib-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f3fbef1aec3c55ecc346d370fdfd1ed4e6729bea61183b8c44054322ae92d2b4",
"md5": "3f4295bbcf1f4fd3d20f73b73f00b9ce",
"sha256": "491e57ba3f687e50d5ce5a52fbd37f6f23b96c47421a46ffda185a451cbe41cd"
},
"downloads": -1,
"filename": "pylan_lib-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3f4295bbcf1f4fd3d20f73b73f00b9ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8843,
"upload_time": "2025-03-01T20:00:46",
"upload_time_iso_8601": "2025-03-01T20:00:46.994859Z",
"url": "https://files.pythonhosted.org/packages/f3/fb/ef1aec3c55ecc346d370fdfd1ed4e6729bea61183b8c44054322ae92d2b4/pylan_lib-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-01 20:00:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TimoKats",
"github_project": "pylan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "python-dateutil",
"specs": []
},
{
"name": "croniter",
"specs": []
}
],
"lcname": "pylan-lib"
}
JSON
