=============================
pibooth-date-folder
=============================
|PythonVersions| |PypiVersion| |Downloads|
``pibooth-date-folder`` is a plugin for the `pibooth`_ application.
.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/pibooth-date-folders.png
:alt: Pibooth image folders, when using this plugin
:align: center
:width: 50%
It organizes ``Photos`` and ``Raw folders`` into per-date folders with a configurable
split time, supporting multiple quoted base directories.
.. contents::
:local:
Requirements
------------
- Python 3.6+
- PiBooth 2.0.8 or later
IMPORTANT — Date/Time must be set correct before using this plugin
------------------------------------------------------------------
This plugin relies on the system date and time to determine when new folders should be created.
You must ensure that the device has a **correct system clock** before running PiBooth. This can be achieved by one of the following:
- **Internet access** for NTP time synchronization
- **A hardware RTC module** (e.g., DS3231)
- **Manually setting the system time** prior to launching PiBooth
⚠️ **Important:** If the system time is incorrect, the plugin will create folders under the *wrong date* or switch at *unexpected times*.
Installation
------------
Run:
.. code-block:: bash
pip3 install pibooth-date-folder
PiBooth will auto-discover the plugin—**no edits** to your `pibooth.cfg` are needed.
Configuration
-------------
On first launch, this plugin adds a `[DATE_FOLDER]` section to your
`~/.config/pibooth/pibooth.cfg`:
.. code-block:: ini
[DATE_FOLDER]
# Hour when a new date-folder starts (0–23, default: 10)
start_hour = 10
# Minute when a new date-folder starts (00–59, default: 00)
start_minute = 00
# Mode for how folder switching is handled: strict (default) or force_today
on_change_mode = strict
Adjust these values in PiBooth’s Settings menu (ESC → Settings) at any time.
Changes take effect at the start of the next photo session.
Setup in Pibooth Menu
---------------------
.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/settings-menu.png
:alt: Pibooth settings menu showing Date_folder entry
:align: center
:width: 60%
.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/date-folder-menu.png
:alt: Date_folder plugin settings screen
:align: center
:width: 60%
**Explanation of options:**
- **start_hour / start_minute**
Define the daily time when a new folder should start. Useful if your events run past midnight but should count as the same “day” (e.g. starting a new folder at 10:00 the next day).
- **on_change_mode**
- ``strict`` *(default)* — The folder switches exactly at the configured time every day, even if no sessions have occurred yet.
- ``force_today`` — The folder automatically switches at midnight (00:00) to match the new calendar date, regardless of the configured threshold time.
The configured time is still included in the folder name for consistency, but it does not affect when switching occurs like ``strict`` does.
Usage
-----
1. **Snapshot original bases**
On configure, the plugin reads your existing quoted
`directory` setting under `[GENERAL]` (one or more paths) and caches them.
2. **Per-session logic** (`state_wait_enter`)
- Builds a “threshold” datetime from `start_hour:start_minute`.
- If you **changed** the threshold since the last session, it treats the next folder as **today**.
- Otherwise, if the current time is **before** the threshold, it treats it as **yesterday**, else **today**.
- Creates a subfolder named::
YYYY-MM-DD_start-hour_HH-MM
- under each of your original base directories.
- Overrides PiBooth’s in-memory directory to the quoted list of these new folders (no pibooth.cfg write).
Note: When the plugin is disabled in the Pibooth menu (General, Manage Plugins), it temporarily reverts
to the default ``~/Pictures/pibooth`` directories in memory only (no pibooth.cfg write).
Testing the Threshold
---------------------
To simulate a day-boundary without waiting 24 hours:
1. In PiBooth’s Settings menu, set `start_hour`/`start_minute` to a time a few minutes **ahead** of now (e.g., it’s 13:58; set to 14:00).
2. Close the menu and take a photo session. Because it’s the **first** session after changing the threshold, the plugin treats it as **today**, creating a folder for today’s date.
3. Take another session **before** the threshold time; since you didn’t change the threshold again, the plugin applies “before threshold → yesterday,” creating a folder for the **prior** date.
4. Take one more session **after** the threshold; it creates a folder for **today** again.
This lets you verify both “yesterday” and “today” folder behavior within minutes.
Examples
--------
Given in your config::
[GENERAL]
directory = "~/Pictures/pibooth", "~/Pictures/backup_booth"
- **Before** threshold (10:00, time 09:30):
Photos saved in::
"~/Pictures/pibooth/2025-07-11_start-hour_10-00", "~/Pictures/backup_booth/2025-07-11_start-hour_10-00"
- **After** threshold (time >10:00):
Photos saved in::
"~/Pictures/pibooth/2025-07-12_start-hour_10-00", "~/Pictures/backup_booth/2025-07-12_start-hour_10-00"
| This version dont write in config file pibooth.cfg
| **BUT If you installed a previous version, your** ``pibooth.cfg`` **may contain a dated folder path.**
| **Remove it/them, before using this version, to avoid nested directories. "See Uninstall below":**
Uninstall
---------
| On current versions (v1.5.7+), the plugin does not write date folders to ``pibooth.cfg``
| So uninstalling typically requires no changes.
|
| BUT if you previously used an older version ´´v1.5.5 an v1.5.6´´ that wrote a extra dated path to the base dir in config,
| you should reset it in ``~/.config/pibooth/pibooth.cfg`` :
|
| Do this
.. code-block:: bash
pibooth --config
Then edit the ``[GENERAL]/directory`` line and remove the dated part, for example:
.. code-block:: ini
[GENERAL]
directory = "~/Pictures/pibooth/2025-07-11_start-hour_10-00"
Change it to:
.. code-block:: ini
[GENERAL]
directory = "~/Pictures/pibooth"
You may also remove the entire ``[DATE_FOLDER]`` section if you wish.
Changelog
---------
- **v1.5.9 (2025-10-08)**
- Fixed unintended `setuptools` auto-upgrade caused by `pyproject.toml`.
- Older Raspberry Pi OS environments will no longer be forced to upgrade `setuptools` during installation.
- v1.5.8 (2025-10-07)
- Fixed plugin registration so the plugin is correctly detected again.
- Pip installation now works as expected.
- v1.5.7 (2025-10-07) — ⚠️⚠️ Important update
🎉 Re-release of the pibooth-date-folder plugin.
**Highlights**
- Automatically organizes photos into date-based folders
- Configurable daily switch time
- Works with multiple base directories
**Changes**
- Changed behavior to no longer write dated directories into the config file
- When disabled via the PiBooth menu, the plugin now temporarily reverts to the default directories in memory only (no ``pibooth.cfg`` write)
- Improved folder creation to be idempotent and avoid duplicate entries
- Normalize base/target paths to ensure existing folders are reused
- Safe directory creation with ``exist_ok=True``
- In-memory override of ``GENERAL/directory``
- Added ``on_change_mode`` (``strict`` default / ``force_today`` override)
- Keeps multiple quoted base paths and ``~`` prefix
- Switched hour range to 0–23 (UI/docs) for clarity
- Legacy value 24 is treated as 00 (midnight) internally
- Clamps minutes to 0–59 for robustness
**Other**
- Update README image links to raw URLs for PyPI rendering
License
-------
GPL-3.0-or-later
Links
-----
`pibooth`_
.. --- Links ------------------------------------------------------------------
.. _`pibooth`: https://pypi.org/project/pibooth
.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/pibooth-date-folder.svg
:target: https://pypi.org/project/pibooth-date-folder
.. |PypiVersion| image:: https://img.shields.io/pypi/v/pibooth-date-folder.svg
:target: https://pypi.org/project/pibooth-date-folder
.. |Downloads| image:: https://img.shields.io/pypi/dm/pibooth-date-folder.svg
:target: https://pypi.org/project/pibooth-date-folder
Raw data
{
"_id": null,
"home_page": "https://github.com/DJ-Dingo/pibooth-date-folder",
"name": "pibooth-date-folder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "pibooth, pibooth plugin, plugin, photobooth, selfiecam, raspberry, raspberry pi, date, folder, sessions, organize, camera, kiosk, Raspberry Pi OS, python",
"author": "Kenneth Nicholas J\u00f8rgensen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b8/a4/e29a2d09cc15586031d77a3948535f13924c985610ab9075947d7e51d11b/pibooth_date_folder-1.5.9.tar.gz",
"platform": null,
"description": "=============================\npibooth-date-folder\n=============================\n\n|PythonVersions| |PypiVersion| |Downloads|\n\n``pibooth-date-folder`` is a plugin for the `pibooth`_ application.\n\n.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/pibooth-date-folders.png\n :alt: Pibooth image folders, when using this plugin\n :align: center\n :width: 50%\n\nIt organizes ``Photos`` and ``Raw folders`` into per-date folders with a configurable\nsplit time, supporting multiple quoted base directories.\n\n.. contents::\n :local:\n\nRequirements\n------------\n- Python 3.6+\n- PiBooth 2.0.8 or later\n\nIMPORTANT \u2014 Date/Time must be set correct before using this plugin\n------------------------------------------------------------------\nThis plugin relies on the system date and time to determine when new folders should be created. \nYou must ensure that the device has a **correct system clock** before running PiBooth. This can be achieved by one of the following:\n\n- **Internet access** for NTP time synchronization \n- **A hardware RTC module** (e.g., DS3231) \n- **Manually setting the system time** prior to launching PiBooth\n\n\u26a0\ufe0f **Important:** If the system time is incorrect, the plugin will create folders under the *wrong date* or switch at *unexpected times*.\n\n\nInstallation\n------------\nRun:\n\n.. code-block:: bash\n\n pip3 install pibooth-date-folder\n\n\nPiBooth will auto-discover the plugin\u2014**no edits** to your `pibooth.cfg` are needed.\n\nConfiguration\n-------------\nOn first launch, this plugin adds a `[DATE_FOLDER]` section to your\n`~/.config/pibooth/pibooth.cfg`:\n\n.. code-block:: ini\n\n [DATE_FOLDER]\n # Hour when a new date-folder starts (0\u201323, default: 10)\n start_hour = 10\n # Minute when a new date-folder starts (00\u201359, default: 00)\n start_minute = 00\n # Mode for how folder switching is handled: strict (default) or force_today\n on_change_mode = strict\n\nAdjust these values in PiBooth\u2019s Settings menu (ESC \u2192 Settings) at any time.\nChanges take effect at the start of the next photo session.\n\nSetup in Pibooth Menu\n---------------------\n\n.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/settings-menu.png\n :alt: Pibooth settings menu showing Date_folder entry\n :align: center\n :width: 60%\n\n.. image:: https://raw.githubusercontent.com/DJ-Dingo/pibooth-date-folder/main/docs/images/date-folder-menu.png\n :alt: Date_folder plugin settings screen\n :align: center\n :width: 60%\n\n\n**Explanation of options:**\n\n- **start_hour / start_minute** \n Define the daily time when a new folder should start. Useful if your events run past midnight but should count as the same \u201cday\u201d (e.g. starting a new folder at 10:00 the next day).\n\n\n- **on_change_mode**\n\n - ``strict`` *(default)* \u2014 The folder switches exactly at the configured time every day, even if no sessions have occurred yet.\n\n - ``force_today`` \u2014 The folder automatically switches at midnight (00:00) to match the new calendar date, regardless of the configured threshold time. \n The configured time is still included in the folder name for consistency, but it does not affect when switching occurs like ``strict`` does.\n\n\nUsage\n-----\n1. **Snapshot original bases** \n On configure, the plugin reads your existing quoted\n `directory` setting under `[GENERAL]` (one or more paths) and caches them.\n\n2. **Per-session logic** (`state_wait_enter`) \n - Builds a \u201cthreshold\u201d datetime from `start_hour:start_minute`. \n - If you **changed** the threshold since the last session, it treats the next folder as **today**. \n - Otherwise, if the current time is **before** the threshold, it treats it as **yesterday**, else **today**. \n - Creates a subfolder named::\n\n\n YYYY-MM-DD_start-hour_HH-MM\n\n\n - under each of your original base directories. \n - Overrides PiBooth\u2019s in-memory directory to the quoted list of these new folders (no pibooth.cfg write).\n\n Note: When the plugin is disabled in the Pibooth menu (General, Manage Plugins), it temporarily reverts\n to the default ``~/Pictures/pibooth`` directories in memory only (no pibooth.cfg write).\n\n\n\nTesting the Threshold\n---------------------\nTo simulate a day-boundary without waiting 24 hours:\n\n1. In PiBooth\u2019s Settings menu, set `start_hour`/`start_minute` to a time a few minutes **ahead** of now (e.g., it\u2019s 13:58; set to 14:00). \n2. Close the menu and take a photo session. Because it\u2019s the **first** session after changing the threshold, the plugin treats it as **today**, creating a folder for today\u2019s date. \n3. Take another session **before** the threshold time; since you didn\u2019t change the threshold again, the plugin applies \u201cbefore threshold \u2192 yesterday,\u201d creating a folder for the **prior** date. \n4. Take one more session **after** the threshold; it creates a folder for **today** again.\n\nThis lets you verify both \u201cyesterday\u201d and \u201ctoday\u201d folder behavior within minutes.\n\nExamples\n--------\nGiven in your config::\n\n\n [GENERAL]\n directory = \"~/Pictures/pibooth\", \"~/Pictures/backup_booth\"\n\n- **Before** threshold (10:00, time 09:30): \n Photos saved in::\n\n\n \"~/Pictures/pibooth/2025-07-11_start-hour_10-00\", \"~/Pictures/backup_booth/2025-07-11_start-hour_10-00\"\n\n- **After** threshold (time >10:00): \n Photos saved in::\n\n\n \"~/Pictures/pibooth/2025-07-12_start-hour_10-00\", \"~/Pictures/backup_booth/2025-07-12_start-hour_10-00\"\n\n\n| This version dont write in config file pibooth.cfg\n| **BUT If you installed a previous version, your** ``pibooth.cfg`` **may contain a dated folder path.** \n| **Remove it/them, before using this version, to avoid nested directories. \"See Uninstall below\":**\n\n\nUninstall\n---------\n| On current versions (v1.5.7+), the plugin does not write date folders to ``pibooth.cfg``\n| So uninstalling typically requires no changes.\n|\n| BUT if you previously used an older version \u00b4\u00b4v1.5.5 an v1.5.6\u00b4\u00b4 that wrote a extra dated path to the base dir in config,\n| you should reset it in ``~/.config/pibooth/pibooth.cfg`` :\n|\n| Do this\n\n.. code-block:: bash\n\n pibooth --config\n\nThen edit the ``[GENERAL]/directory`` line and remove the dated part, for example:\n\n.. code-block:: ini\n\n [GENERAL]\n directory = \"~/Pictures/pibooth/2025-07-11_start-hour_10-00\"\n\nChange it to:\n\n.. code-block:: ini\n\n [GENERAL]\n directory = \"~/Pictures/pibooth\"\n\nYou may also remove the entire ``[DATE_FOLDER]`` section if you wish.\n\n\nChangelog\n---------\n\n- **v1.5.9 (2025-10-08)**\n \n - Fixed unintended `setuptools` auto-upgrade caused by `pyproject.toml`. \n - Older Raspberry Pi OS environments will no longer be forced to upgrade `setuptools` during installation.\n\n\n- v1.5.8 (2025-10-07)\n\n - Fixed plugin registration so the plugin is correctly detected again.\n - Pip installation now works as expected.\n\n\n- v1.5.7 (2025-10-07) \u2014 \u26a0\ufe0f\u26a0\ufe0f Important update\n\n \ud83c\udf89 Re-release of the pibooth-date-folder plugin.\n\n **Highlights**\n \n - Automatically organizes photos into date-based folders\n - Configurable daily switch time\n - Works with multiple base directories\n\n **Changes**\n \n - Changed behavior to no longer write dated directories into the config file\n - When disabled via the PiBooth menu, the plugin now temporarily reverts to the default directories in memory only (no ``pibooth.cfg`` write)\n - Improved folder creation to be idempotent and avoid duplicate entries\n - Normalize base/target paths to ensure existing folders are reused\n - Safe directory creation with ``exist_ok=True``\n - In-memory override of ``GENERAL/directory``\n - Added ``on_change_mode`` (``strict`` default / ``force_today`` override)\n - Keeps multiple quoted base paths and ``~`` prefix\n - Switched hour range to 0\u201323 (UI/docs) for clarity\n - Legacy value 24 is treated as 00 (midnight) internally\n - Clamps minutes to 0\u201359 for robustness\n\n **Other**\n \n - Update README image links to raw URLs for PyPI rendering\n\n\n\nLicense\n-------\nGPL-3.0-or-later\n\nLinks\n-----\n`pibooth`_ \n\n.. --- Links ------------------------------------------------------------------\n\n.. _`pibooth`: https://pypi.org/project/pibooth\n\n.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/pibooth-date-folder.svg\n :target: https://pypi.org/project/pibooth-date-folder\n.. |PypiVersion| image:: https://img.shields.io/pypi/v/pibooth-date-folder.svg\n :target: https://pypi.org/project/pibooth-date-folder\n.. |Downloads| image:: https://img.shields.io/pypi/dm/pibooth-date-folder.svg\n :target: https://pypi.org/project/pibooth-date-folder\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "PiBooth plugin to split/save sessions into date-based folders with an optional daily time threshold.",
"version": "1.5.9",
"project_urls": {
"Homepage": "https://github.com/DJ-Dingo/pibooth-date-folder",
"Issues": "https://github.com/DJ-Dingo/pibooth-date-folder/issues",
"Repository": "https://github.com/DJ-Dingo/pibooth-date-folder"
},
"split_keywords": [
"pibooth",
" pibooth plugin",
" plugin",
" photobooth",
" selfiecam",
" raspberry",
" raspberry pi",
" date",
" folder",
" sessions",
" organize",
" camera",
" kiosk",
" raspberry pi os",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4da059d85a0d560636ebcbd2ebc4ce4f08372abf003bdf63431245d337dd5d25",
"md5": "38ed189021d29079a4910e3bdbc7a153",
"sha256": "e52b5743eb5cd961a24172e0cf75c560f1bbde65027a2f069303ce295b1bef66"
},
"downloads": -1,
"filename": "pibooth_date_folder-1.5.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38ed189021d29079a4910e3bdbc7a153",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 21383,
"upload_time": "2025-10-07T23:35:28",
"upload_time_iso_8601": "2025-10-07T23:35:28.787848Z",
"url": "https://files.pythonhosted.org/packages/4d/a0/59d85a0d560636ebcbd2ebc4ce4f08372abf003bdf63431245d337dd5d25/pibooth_date_folder-1.5.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b8a4e29a2d09cc15586031d77a3948535f13924c985610ab9075947d7e51d11b",
"md5": "5d02b3d8d253a53423e500324a07d08b",
"sha256": "a15b8d78e9aa88feabed14866538b3c4043e83fc0f35cbf7dd9f476f1dfe8002"
},
"downloads": -1,
"filename": "pibooth_date_folder-1.5.9.tar.gz",
"has_sig": false,
"md5_digest": "5d02b3d8d253a53423e500324a07d08b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 78066,
"upload_time": "2025-10-07T23:35:29",
"upload_time_iso_8601": "2025-10-07T23:35:29.889896Z",
"url": "https://files.pythonhosted.org/packages/b8/a4/e29a2d09cc15586031d77a3948535f13924c985610ab9075947d7e51d11b/pibooth_date_folder-1.5.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 23:35:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DJ-Dingo",
"github_project": "pibooth-date-folder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pibooth-date-folder"
}
JSON
