fix: license mismatch, import shadowing, packaging, AsyncLogger shutdown, magic numbers, CONTRIBUTING.md

Co-authored-by: IntegerAlex <84370725+IntegerAlex@users.noreply.github.com>

Author: Copilot

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Kakashi
+
+Thank you for your interest in contributing! The following guidelines will help you get started.
+
+## Reporting Issues
+
+- Search [existing issues](https://github.com/IntegerAlex/kakashi/issues) before opening a new one.
+- Include a minimal, reproducible example and your Python version when reporting bugs.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/IntegerAlex/kakashi.git
+cd kakashi
+
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Code Style
+
+- Format code with [black](https://black.readthedocs.io/): `black .`
+- Lint with [flake8](https://flake8.pycqa.org/): `flake8 kakashi/`
+- Type-check with [mypy](https://mypy.readthedocs.io/): `mypy kakashi/`
+
+## Submitting a Pull Request
+
+1. Fork the repository and create a feature branch from `main`.
+2. Write tests for any new functionality.
+3. Ensure all tests, lint, and type checks pass.
+4. Open a pull request with a clear description of the change.
+
+## License
+
+By contributing you agree that your code will be released under the project's [LGPL-2.1 license](LICENSE).

README.md

@@ -235,7 +235,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the GNU Lesser General Public License v2.1 (LGPL-2.1) - see the [LICENSE](LICENSE) file for details.
 
 ## ⚖️ Legal Disclaimers
 

__init__.py

@@ -42,7 +42,8 @@
 from .core.logger import (
     Logger, AsyncLogger, LogFormatter,
     get_logger, get_async_logger, clear_logger_cache,
-    shutdown_async_logging
+    shutdown_async_logging,
+    LOG_LEVEL_DEBUG, LOG_LEVEL_INFO, LOG_LEVEL_WARNING, LOG_LEVEL_ERROR, LOG_LEVEL_CRITICAL,
 )
 
 # ============================================================================
@@ -99,6 +100,13 @@
     "get_async_logger",  # Async logger entry point
     "clear_logger_cache",
     "shutdown_async_logging",
+
+    # ---- LOG LEVEL CONSTANTS ----
+    "LOG_LEVEL_DEBUG",
+    "LOG_LEVEL_INFO",
+    "LOG_LEVEL_WARNING",
+    "LOG_LEVEL_ERROR",
+    "LOG_LEVEL_CRITICAL",
 
     # ---- CORE DATA STRUCTURES ----
     "LogRecord",

kakashi/__init__.py

@@ -12,6 +12,7 @@
 - Professional, maintainable code structure
 """
 
+import atexit
 import threading
 import time
 import sys
@@ -21,12 +22,22 @@
 # Pre-computed constants for fast access
 _LEVEL_NAMES = {
     10: 'DEBUG',
-    20: 'INFO', 
+    20: 'INFO',
     30: 'WARNING',
     40: 'ERROR',
     50: 'CRITICAL'
 }
 
+# Named log-level constants (use these instead of bare integers)
+LOG_LEVEL_DEBUG = 10
+LOG_LEVEL_INFO = 20
+LOG_LEVEL_WARNING = 30
+LOG_LEVEL_ERROR = 40
+LOG_LEVEL_CRITICAL = 50
+
+# Wait time (seconds) for AsyncLogger.close() best-effort flush
+_ASYNC_CLOSE_WAIT_SECS = 0.05
+
 # Thread-local storage for lock-free operation
 _thread_local = threading.local()
 
@@ -146,7 +157,7 @@ class Logger:
 
     __slots__ = ('name', 'min_level', 'formatter')
 
-    def __init__(self, name: str, min_level: int = 20):
+    def __init__(self, name: str, min_level: int = LOG_LEVEL_INFO):
         self.name = name
         self.min_level = min_level
         self.formatter = LogFormatter()
@@ -236,12 +247,19 @@ class AsyncLogger:
     - Superior throughput vs sync logging
     """
 
-    def __init__(self, name: str, min_level: int = 20):
+    def __init__(self, name: str, min_level: int = LOG_LEVEL_INFO):
         self.name = name
         self.min_level = min_level
-        
+
         # Ensure async worker is running
         _ensure_async_worker()
+
+    def close(self) -> None:
+        """Flush pending messages and release resources for this logger instance."""
+        # Draining items belonging to this logger from the queue would require
+        # restructuring the shared queue, so we do a best-effort flush by
+        # waiting briefly for the background worker to catch up.
+        time.sleep(_ASYNC_CLOSE_WAIT_SECS)
 
     def _log_async(self, level: int, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
         """True asynchronous logging - non-blocking enqueue."""
@@ -302,7 +320,7 @@ def flush(self) -> None:
 _cache_lock = threading.RLock()
 
 
-def get_logger(name: str, min_level: int = 20) -> Logger:
+def get_logger(name: str, min_level: int = LOG_LEVEL_INFO) -> Logger:
     """
     Get a high-performance logger instance with minimal lock contention.
     
@@ -324,7 +342,7 @@ def get_logger(name: str, min_level: int = 20) -> Logger:
         return logger
 
 
-def get_async_logger(name: str, min_level: int = 20) -> AsyncLogger:
+def get_async_logger(name: str, min_level: int = LOG_LEVEL_INFO) -> AsyncLogger:
     """
     Get an asynchronous logger instance with minimal lock contention.
     
@@ -366,3 +384,7 @@ def shutdown_async_logging() -> None:
         # Wait for worker to finish (with timeout)
         _async_worker.join(timeout=1.0)
         _async_worker = None
+
+
+# Ensure buffered async messages are flushed when the interpreter exits
+atexit.register(shutdown_async_logging)