tj-logger 1.13__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,98 @@
1
+ Metadata-Version: 2.3
2
+ Name: tj-logger
3
+ Version: 1.13
4
+ Summary: simple logger setup
5
+ Author: tjf1dev
6
+ Author-email: tjf1dev <hi@tjf1.dev>
7
+ Requires-Dist: ansik>=0.1.0
8
+ Requires-Python: >=3.6
9
+ Description-Content-Type: text/markdown
10
+
11
+ # tjf1's logger setup
12
+
13
+ simple python logger setup i use in most of my projects
14
+ <img width="760" height="181" alt="showcase" src="https://github.com/user-attachments/assets/8d8b615b-061e-4bda-9408-1c3a58d71205" />
15
+
16
+ ## features
17
+
18
+ - easy to install and use
19
+ - clean, simple logs
20
+ - `OK` level to indicate successful actions
21
+ - file logging
22
+
23
+ ## install
24
+
25
+ > ![WARNING]
26
+ > it is very recommended to use a virtual environment.
27
+
28
+ ### as dependency
29
+
30
+ ```bash
31
+ pip install tj-logger
32
+ ```
33
+
34
+ or
35
+
36
+ ```bash
37
+ uv add tj-logger
38
+ ```
39
+
40
+ ## usage
41
+
42
+ ```py
43
+ import logger
44
+ logger.info("hello world!")
45
+ # > DD/MM/YYYY HH:MM:SS [ INFO ] hello world! (<module>)
46
+ ```
47
+
48
+ ## file logging
49
+
50
+ > [!WARNING]
51
+ > file logging is disabled by default! enable it in [settings](#settings)
52
+
53
+ the logger setup has file logging built in.
54
+ it creates them to a folder names `logs` by default
55
+ with a `latest.log` and a log file for every session
56
+
57
+ ## settings
58
+
59
+ to change the default behavior, open `logger/__init__.py`
60
+
61
+ - `FILE_LOGGING`: is file logging enabled
62
+ - `LOG_PATH`: the name of the directory to save logs to
63
+ - `FILENAME_DATE_STR`: the name of the log files ([available codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
64
+ - <details>
65
+ <summary>available codes</summary>
66
+
67
+ | Directive | Meaning | Example |
68
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
69
+ | %a | Weekday as locale’s abbreviated name. | Sun, Mon, …, Sat (en_US); So, Mo, …, Sa (de_DE) |
70
+ | %A | Weekday as locale’s full name. | Sunday, Monday, …, Saturday (en_US); Sonntag, Montag, …, Samstag (de_DE) |
71
+ | %w | Weekday as a decimal number, where 0 is Sunday and 6 is Saturday. | 0, 1, …, 6 |
72
+ | %d | Day of the month as a zero-padded decimal number. | 01, 02, …, 31 |
73
+ | %b | Month as locale’s abbreviated name. | Jan, Feb, …, Dec (en_US); Jan, Feb, …, Dez (de_DE) |
74
+ | %B | Month as locale’s full name. | January, February, …, December (en_US); Januar, Februar, …, Dezember (de_DE) |
75
+ | %m | Month as a zero-padded decimal number. | 01, 02, …, 12 |
76
+ | %y | Year without century as a zero-padded decimal number. | 00, 01, …, 99 |
77
+ | %Y | Year with century as a decimal number. | 0001, 0002, …, 2013, 2014, …, 9998, 9999 |
78
+ | %H | Hour (24-hour clock) as a zero-padded decimal number. | 00, 01, …, 23 |
79
+ | %I | Hour (12-hour clock) as a zero-padded decimal number. | 01, 02, …, 12 |
80
+ | %p | Locale’s equivalent of either AM or PM. | AM, PM (en_US); am, pm (de_DE) |
81
+ | %M | Minute as a zero-padded decimal number. | 00, 01, …, 59 |
82
+ | %S | Second as a zero-padded decimal number. | 00, 01, …, 59 |
83
+ | %f | Microsecond as a decimal number, zero-padded to 6 digits. | 000000, 000001, …, 999999 |
84
+ | %z | UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive). | (empty), +0000, -0400, +1030, +063415, -030712.345216 |
85
+ | %Z | Time zone name (empty string if the object is naive). | (empty), UTC, GMT |
86
+ | %j | Day of the year as a zero-padded decimal number. | 001, 002, …, 366 |
87
+ | %U | Week number of the year (Sunday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0. | 00, 01, …, 53 |
88
+ | %W | Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0. | 00, 01, …, 53 |
89
+ | %c | Locale’s appropriate date and time representation. | Tue Aug 16 21:30:00 1988 (en_US); Di 16 Aug 21:30:00 1988 (de_DE) |
90
+ | %x | Locale’s appropriate date representation. | 08/16/88 (None); 08/16/1988 (en_US); 16.08.1988 (de_DE) |
91
+ | %X | Locale’s appropriate time representation. | 21:30:00 (en_US); 21:30:00 (de_DE) |
92
+ | %% | A literal '%' character. | % |
93
+
94
+ </details>
95
+
96
+ - ([from python's docs](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
97
+
98
+ - `LEVEL`: default logger level
@@ -0,0 +1,88 @@
1
+ # tjf1's logger setup
2
+
3
+ simple python logger setup i use in most of my projects
4
+ <img width="760" height="181" alt="showcase" src="https://github.com/user-attachments/assets/8d8b615b-061e-4bda-9408-1c3a58d71205" />
5
+
6
+ ## features
7
+
8
+ - easy to install and use
9
+ - clean, simple logs
10
+ - `OK` level to indicate successful actions
11
+ - file logging
12
+
13
+ ## install
14
+
15
+ > ![WARNING]
16
+ > it is very recommended to use a virtual environment.
17
+
18
+ ### as dependency
19
+
20
+ ```bash
21
+ pip install tj-logger
22
+ ```
23
+
24
+ or
25
+
26
+ ```bash
27
+ uv add tj-logger
28
+ ```
29
+
30
+ ## usage
31
+
32
+ ```py
33
+ import logger
34
+ logger.info("hello world!")
35
+ # > DD/MM/YYYY HH:MM:SS [ INFO ] hello world! (<module>)
36
+ ```
37
+
38
+ ## file logging
39
+
40
+ > [!WARNING]
41
+ > file logging is disabled by default! enable it in [settings](#settings)
42
+
43
+ the logger setup has file logging built in.
44
+ it creates them to a folder names `logs` by default
45
+ with a `latest.log` and a log file for every session
46
+
47
+ ## settings
48
+
49
+ to change the default behavior, open `logger/__init__.py`
50
+
51
+ - `FILE_LOGGING`: is file logging enabled
52
+ - `LOG_PATH`: the name of the directory to save logs to
53
+ - `FILENAME_DATE_STR`: the name of the log files ([available codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
54
+ - <details>
55
+ <summary>available codes</summary>
56
+
57
+ | Directive | Meaning | Example |
58
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
59
+ | %a | Weekday as locale’s abbreviated name. | Sun, Mon, …, Sat (en_US); So, Mo, …, Sa (de_DE) |
60
+ | %A | Weekday as locale’s full name. | Sunday, Monday, …, Saturday (en_US); Sonntag, Montag, …, Samstag (de_DE) |
61
+ | %w | Weekday as a decimal number, where 0 is Sunday and 6 is Saturday. | 0, 1, …, 6 |
62
+ | %d | Day of the month as a zero-padded decimal number. | 01, 02, …, 31 |
63
+ | %b | Month as locale’s abbreviated name. | Jan, Feb, …, Dec (en_US); Jan, Feb, …, Dez (de_DE) |
64
+ | %B | Month as locale’s full name. | January, February, …, December (en_US); Januar, Februar, …, Dezember (de_DE) |
65
+ | %m | Month as a zero-padded decimal number. | 01, 02, …, 12 |
66
+ | %y | Year without century as a zero-padded decimal number. | 00, 01, …, 99 |
67
+ | %Y | Year with century as a decimal number. | 0001, 0002, …, 2013, 2014, …, 9998, 9999 |
68
+ | %H | Hour (24-hour clock) as a zero-padded decimal number. | 00, 01, …, 23 |
69
+ | %I | Hour (12-hour clock) as a zero-padded decimal number. | 01, 02, …, 12 |
70
+ | %p | Locale’s equivalent of either AM or PM. | AM, PM (en_US); am, pm (de_DE) |
71
+ | %M | Minute as a zero-padded decimal number. | 00, 01, …, 59 |
72
+ | %S | Second as a zero-padded decimal number. | 00, 01, …, 59 |
73
+ | %f | Microsecond as a decimal number, zero-padded to 6 digits. | 000000, 000001, …, 999999 |
74
+ | %z | UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive). | (empty), +0000, -0400, +1030, +063415, -030712.345216 |
75
+ | %Z | Time zone name (empty string if the object is naive). | (empty), UTC, GMT |
76
+ | %j | Day of the year as a zero-padded decimal number. | 001, 002, …, 366 |
77
+ | %U | Week number of the year (Sunday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0. | 00, 01, …, 53 |
78
+ | %W | Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0. | 00, 01, …, 53 |
79
+ | %c | Locale’s appropriate date and time representation. | Tue Aug 16 21:30:00 1988 (en_US); Di 16 Aug 21:30:00 1988 (de_DE) |
80
+ | %x | Locale’s appropriate date representation. | 08/16/88 (None); 08/16/1988 (en_US); 16.08.1988 (de_DE) |
81
+ | %X | Locale’s appropriate time representation. | 21:30:00 (en_US); 21:30:00 (de_DE) |
82
+ | %% | A literal '%' character. | % |
83
+
84
+ </details>
85
+
86
+ - ([from python's docs](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
87
+
88
+ - `LEVEL`: default logger level
@@ -0,0 +1,18 @@
1
+ [project]
2
+ name = "tj-logger"
3
+ version = "1.13"
4
+ description = "simple logger setup"
5
+ readme = "README.md"
6
+ requires-python = ">=3.6"
7
+ dependencies = ["ansik>=0.1.0"]
8
+
9
+ [[project.authors]]
10
+ name = "tjf1dev"
11
+ email = "hi@tjf1.dev"
12
+
13
+ [project.scripts]
14
+ logger = "logger:main"
15
+
16
+ [build-system]
17
+ requires = ["uv_build>=0.12.23,<0.13.0"]
18
+ build-backend = "uv_build"
@@ -0,0 +1,15 @@
1
+ [project]
2
+ name = "tj-logger"
3
+ version = "1.13"
4
+ description = "simple logger setup"
5
+ readme = "README.md"
6
+ authors = [{ name = "tjf1dev", email = "hi@tjf1.dev" }]
7
+ requires-python = ">=3.6"
8
+ dependencies = ["ansik>=0.1.0"]
9
+
10
+ [project.scripts]
11
+ logger = "logger:main"
12
+
13
+ [build-system]
14
+ requires = ["uv_build>=0.12.23,<0.13.0"]
15
+ build-backend = "uv_build"
@@ -0,0 +1,158 @@
1
+ """
2
+ MIT License
3
+
4
+ Copyright (c) 2026 tjf1
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
23
+
24
+ tjf1's logger setup!
25
+ feel free to use, modify however you want
26
+ """
27
+
28
+ import datetime
29
+ import logging
30
+ from pathlib import Path
31
+ from typing import Any, cast
32
+
33
+ from ansik import ansik
34
+
35
+ # configuration
36
+
37
+ LEVEL = logging.DEBUG
38
+ FILE_LOGGING = False
39
+ LOG_PATH = "logs"
40
+ FILENAME_DATE_STR = "%Y-%m-%d_%H-%M-%S"
41
+
42
+ DATE_FORMAT = "%d/%m/%Y %H:%M:%S"
43
+ DEFAULT_FORMAT = "%(asctime)s [ %(levelname)s ] %(message)s (%(funcName)s)"
44
+
45
+ OK_LEVEL = 25
46
+ logging.addLevelName(OK_LEVEL, "OK")
47
+
48
+
49
+ COLORS = {
50
+ "DEBUG": ansik.F.BRIGHT_BLACK,
51
+ "INFO": ansik.F.BRIGHT_CYAN,
52
+ "WARNING": ansik.F.YELLOW,
53
+ "ERROR": ansik.F.RED,
54
+ "CRITICAL": ansik.F.MAGENTA,
55
+ "OK": ansik.F.BRIGHT_GREEN,
56
+ }
57
+
58
+
59
+ class ColorFormatter(logging.Formatter):
60
+ """Logging formatter that adds ANSI colors to console output."""
61
+
62
+ def format(self, record: logging.LogRecord) -> str:
63
+ """Format a log record with colors based on its severity."""
64
+
65
+ log_color = COLORS.get(record.levelname, ansik.F.WHITE)
66
+
67
+ timestamp = self.formatTime(record, self.datefmt)
68
+ levelname = f"{log_color}{record.levelname}{ansik.RESET}"
69
+ message = f"{log_color}{record.getMessage()}{ansik.RESET}"
70
+ function = f"{ansik.F.BRIGHT_BLACK}({record.funcName}){ansik.RESET}"
71
+
72
+ return f"{timestamp} [ {levelname} ] {message} {function}"
73
+
74
+
75
+ class tjLogger(logging.Logger):
76
+ def ok(self, message: object, *args: object, **kwargs: Any) -> None:
77
+ if self.isEnabledFor(OK_LEVEL):
78
+ self._log(OK_LEVEL, message, args, stacklevel=2, **kwargs)
79
+
80
+
81
+ def make_formatter(color: bool = False) -> logging.Formatter:
82
+ formatter = ColorFormatter if color else logging.Formatter
83
+
84
+ return formatter(
85
+ DEFAULT_FORMAT,
86
+ datefmt=DATE_FORMAT,
87
+ )
88
+
89
+
90
+ def setup_logger() -> tjLogger:
91
+ logging.setLoggerClass(tjLogger)
92
+
93
+ logger = cast(tjLogger, logging.getLogger(__name__))
94
+ logger.handlers.clear()
95
+ logger.setLevel(LEVEL)
96
+ logger.propagate = False
97
+
98
+ console_handler = logging.StreamHandler()
99
+ console_handler.setFormatter(make_formatter(color=True))
100
+ logger.addHandler(console_handler)
101
+
102
+ if FILE_LOGGING:
103
+ Path(LOG_PATH).mkdir(parents=True, exist_ok=True)
104
+
105
+ timestamp = datetime.datetime.now().astimezone().strftime(FILENAME_DATE_STR)
106
+
107
+ file_handlers = [
108
+ (Path(LOG_PATH) / "latest.log", "w"),
109
+ (Path(LOG_PATH) / f"{timestamp}.log", "a"),
110
+ ]
111
+
112
+ for path, mode in file_handlers:
113
+ handler = logging.FileHandler(path, mode=mode, encoding="utf-8")
114
+ handler.setFormatter(make_formatter())
115
+ logger.addHandler(handler)
116
+
117
+ return logger
118
+
119
+
120
+ logger = setup_logger()
121
+
122
+
123
+ info = logger.info
124
+ debug = logger.debug
125
+ warning = logger.warning
126
+ error = logger.error
127
+ critical = logger.critical
128
+ ok = logger.ok
129
+
130
+
131
+ __all__ = [
132
+ "COLORS",
133
+ "FILENAME_DATE_STR",
134
+ "FILE_LOGGING",
135
+ "LEVEL",
136
+ "LOG_PATH",
137
+ "ColorFormatter",
138
+ "critical",
139
+ "debug",
140
+ "error",
141
+ "info",
142
+ "logger",
143
+ "ok",
144
+ "warning",
145
+ ]
146
+
147
+
148
+ def main() -> None:
149
+ logger.critical("CRITICAL")
150
+ logger.error("ERROR")
151
+ logger.warning("WARNING")
152
+ logger.ok("OK")
153
+ logger.info("INFO")
154
+ logger.debug("DEBUG")
155
+
156
+
157
+ if __name__ == "__main__":
158
+ main()