Release v3.0.0

docs/admin/release_notes/version_3.0.md

@@ -0,0 +1,14 @@
+# v3.0 Release Notes
+
+This document describes all new features and changes in the release. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Release Overview
+
+- Pyntc now requires the `PYNTC_LOG_FILE` environment variable to output logging to a file. The new default behavior is to only log to stderr.
+
+<!-- towncrier release notes start -->
+## [v3.0.0 (2026-05-06)](https://github.com/networktocode/pyntc/releases/tag/v3.0.0)
+
+### Breaking Changes
+
+- [#383](https://github.com/networktocode/pyntc/issues/383) - The pyntc rotating file handler is now opt-in via the `PYNTC_LOG_FILE` environment variable. When unset, no log file is created. When set, its value is used as the log file path, and the handler is registered only once per logger to avoid duplicate entries on repeated `get_log` calls.

docs/user/lib_getting_started.md

@@ -342,6 +342,23 @@ Full workflow example:
 >>>
 ```
 
+# Logging
+
+pyntc reads several environment variables to configure logging. None of them are required; all are read at runtime.
+
+| Variable | Description |
+| --- | --- |
+| `PYNTC_LOG_LEVEL` | Log level for the `pyntc` logger (e.g. `debug`, `info`, `warning`). Defaults to `info`. |
+| `PYNTC_DEBUG` | When set to any non-empty value, forces the log level to `DEBUG` and switches to a more verbose log format. |
+| `PYNTC_LOG_FILE` | Path to a file that pyntc should log to. When set, a `RotatingFileHandler` (2000 byte rotation) is attached to the logger using this path. When unset, no file handler is attached; log records still propagate to the root logger configured by `logging.basicConfig` (called from `pyntc.log.init` during device initialization) or by the calling application. |
+
+Example:
+
+```bash
+export PYNTC_LOG_FILE=/var/log/pyntc.log
+export PYNTC_LOG_LEVEL=debug
+```
+
 #### Cisco IOS Install Mode Option
 
 New in 0.15 there is support for [Install Mode](https://content.cisco.com/chapter.sjs?uri=/searchable/chapter/c/en/us/td/docs/switches/lan/Denali_16-1/ConfigExamples_Technotes/Config_Examples/Misc/qos/m_install_vs_bundle.html.xml) upgrades. To execute this there is an option (defaults to False) to run install mode. **file_copy must be executed before install_os**

mkdocs.yml

@@ -132,6 +132,7 @@ nav:
       - Uninstall: "admin/uninstall.md"
       - Release Notes:
           - "admin/release_notes/index.md"
+          - v3.0: "admin/release_notes/version_3.0.md"
           - v2.4: "admin/release_notes/version_2.4.md"
           - v2.3: "admin/release_notes/version_2.3.md"
           - v2.2: "admin/release_notes/version_2.2.md"

pyntc/log.py

@@ -17,17 +17,25 @@
 def get_log(name=None):
     """Get log namespace and creates logger and rotating file handler.
 
+    A :class:`RotatingFileHandler` is attached if the ``PYNTC_LOG_FILE``
+    environment variable is set, in which case its value is used as the log
+    file path.
+
     Args:
         name (str, optional): Sublogger name. Defaults to None.
 
     Returns:
         (logger): Return a logger instance in the :data:`APP` namespace.
     """
     logger_name = f"{APP}.{name}" if name else APP
-    # file handler
-    handler = RotatingFileHandler(f"{logger_name}.log", maxBytes=2000)
     _logger = logging.getLogger(logger_name)
-    _logger.addHandler(handler)
+
+    log_file = os.environ.get("PYNTC_LOG_FILE")
+    if log_file and not any(
+        isinstance(h, RotatingFileHandler) and getattr(h, "baseFilename", None) == os.path.abspath(log_file)
+        for h in _logger.handlers
+    ):
+        _logger.addHandler(RotatingFileHandler(log_file, maxBytes=2000))
 
     return _logger
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pyntc"
-version = "2.4.1"
+version = "3.0.0"
 description = "Python library focused on tasks related to device level and OS management."
 authors = ["Network to Code, LLC <opensource@networktocode.com>"]
 readme = "README.md"
@@ -172,7 +172,7 @@ addopts = "-vv --doctest-modules -p no:warnings --ignore-glob='*mock*'"
 [tool.towncrier]
 package = "pyntc"
 directory = "changes"
-filename = "docs/admin/release_notes/version_2.4.md"
+filename = "docs/admin/release_notes/version_3.0.md"
 template = "towncrier_template.j2"
 start_string = "<!-- towncrier release notes start -->"
 issue_format = "[#{issue}](https://github.com/networktocode/pyntc/issues/{issue})"

towncrier_template.j2

@@ -1,4 +1,3 @@
-
 # v{{ versiondata.version.split(".")[:2] | join(".") }} Release Notes
 
 This document describes all new features and changes in the release. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -8,6 +7,7 @@ This document describes all new features and changes in the release. The format
 - Major features or milestones
 - Changes to compatibility with Nautobot and/or other apps, libraries etc.
 
+<!-- towncrier release notes start -->
 {% if render_title %}
 ## [v{{ versiondata.version }} ({{ versiondata.date }})](https://github.com/networktocode/pyntc/releases/tag/v{{ versiondata.version}})
 
@@ -40,4 +40,3 @@ No significant changes.
 
 {% endif %}
 {% endfor %}
-