Metadata-Version: 2.4
Name: ctimed_rotating_file_handler
Version: 0.2.0
Summary: TimedRotatingFileHandler using ctime instead of mtime to determine rollover times.
Author-email: Silmaril <python@silmaril.de>
License: This is free and unencumbered software released into the public domain.
        
        Anyone is free to copy, modify, publish, use, compile, sell, or
        distribute this software, either in source code form or as a compiled
        binary, for any purpose, commercial or non-commercial, and by any
        means.
        
        In jurisdictions that recognize copyright laws, the author or authors
        of this software dedicate any and all copyright interest in the
        software to the public domain. We make this dedication for the benefit
        of the public at large and to the detriment of our heirs and
        successors. We intend this dedication to be an overt act of
        relinquishment in perpetuity of all present and future rights to this
        software under copyright law.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
        
        For more information, please refer to <https://unlicense.org>
        
Project-URL: Homepage, https://codeberg.org/silmaril/CTimedRotatingFileHandler
Project-URL: Bug Tracker, https://codeberg.org/silmaril/CTimedRotatingFileHandler/issues
Keywords: logging,filetime
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: win32-setctime==1.2.0; platform_system == "Windows"
Dynamic: license-file

# CTimedRotatingFileHandler

TimedRotatingFileHandler for python logging, that uses `ctime` instead of `mtime` to determine rollover times.

This module provides `CTimedRotatingFileHandler` as a subclass of `logging.handlers.TimedRotatingFileHandler`.
It uses file creation time instead of file modification time to calculate the next rollover time.

It also contains a workaround for "file system tunneling" on Windows, which prevents new files from having new
creation times if they have already existed a short time ago.  
To be able to do this, a new dependency to `win32-setctime` is introduced (only needed if running on Windows).

## Usage Example

```py
import logging
from ctimed_rotating_file_handler import CTimedRotatingFileHandler

logfile = 'path/to/logdir/MyName.log'
loglevel = logging.DEBUG
backupcount = 7
logformat = '%(asctime)s\t%(levelname)s\t%(name)s\t%(message)s'

logger = logging.getLogger()
formatter = logging.Formatter(fmt=logformat)
loghandler = CTimedRotatingFileHandler(logfile, when='midnight', interval=1, backupCount=backupcount)
loghandler.setFormatter(formatter)
logging.root.addHandler(loghandler)
logging.root.setLevel(loglevel)

logger.info('This is an information.')
```

---

## Development and building

### Prerequesites

This project uses [uv](https://docs.astral.sh/uv/) for development, build and deploy, so `uv` has to be installed and
must be found on the system PATH.

All project settings can be found in `pyproject.toml`.

### Setup development environment

After cloning the repo, run `uv sync` once to set up a venv with all dependencies in the directory `.venv`.

### Building the package

You might want to change `project.version` in `pyproject.toml` before building (eg. add `.dev1` to it), so you always
know which one you are dealing with.

To build the project, run this command from inside the project directory (the same directory that contains
`pyproject.toml`):

```
uv build
```

This will create `.whl` and `.tar.gz` in the directory `dist`.

## Deployment

Before deploying to `pypi.org` or `test.pypi.org`, make sure the correct new version is entered in `pyproject.toml`.

Delete the `dist` folder and build the latest version so only this version is present (`uv` will try to upload all 
versions it can find in the folder).

### Test-Release on https://test.pypi.org

- Set the environment variable `UV_PUBLISH_TOKEN` to a `test.pypi.org`-token with privileges for this project.
- Call `uv publish` with publish-url set to https://test.pypi.org/legacy/ 

Windows:
```powershell
$env:UV_PUBLISH_TOKEN = "pypi-..."
uv publish --publish-url https://test.pypi.org/legacy/
```

Linux
```bash
export UV_PUBLISH_TOKEN="pypi-..."
uv publish --publish-url https://test.pypi.org/legacy/ 
```

### Release on https://pypi.org

- Set the environment variable `UV_PUBLISH_TOKEN` to a `pypi.org`-token with privileges for this project.
- Call `uv publish` with no additional arguments 

Windows:
```powershell
$env:UV_PUBLISH_TOKEN = "pypi-..."
uv publish
```

Linux
```bash
export UV_PUBLISH_TOKEN="pypi-..."
uv publish 
```
