Merge pull request #24 from liquidz00/develop

Merge version 2.0 functionality from develop into main

Author: liquidz00

Makefile

@@ -1,6 +1,9 @@
 SHELL := /bin/bash
 .PHONY: docs
 
+install:
+	python3 -m pip install --upgrade --force-reinstall --editable '.[all]'
+
 install-dev:
 	python3 -m pip install --upgrade --force-reinstall --editable '.[dev]'
 
@@ -32,3 +35,4 @@ build:
 
 docs:
 	sphinx-build -b html docs/ docs/_build/
+

README.md

@@ -1,37 +1,59 @@
-# Patcher
-
-_Patch reporting simplified_
+<p align="left">
+    <a href="https://patcher.liquidzoo.io/">
+        <img src="docs/_static/patcher-banner-readme.svg" width="540"/>
+    </a>
+</p>
 
 ![](https://img.shields.io/pypi/l/patcherctl)&nbsp;![](https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat&logo=python&logoColor=white)&nbsp;![](https://img.shields.io/github/v/release/liquidz00/Patcher?color=orange)&nbsp;![](https://github.com/liquidz00/patcher/actions/workflows/pytest.yml/badge.svg)&nbsp;![](https://img.shields.io/pypi/v/patcherctl?color=yellow)
 
+----
 
-Patcher leverages the Jamf Pro API to fetch patch management data and generate comprehensive reports in both Excel and PDF formats. It simplifies tracking and reporting on software update compliance across macOS devices managed through Jamf Pro.
+# Patcher
 
-## Documentation
-Project documentation can now be found [on our project homepage](https://patcher.liquidzoo.io). All content from our project wiki has been migrated to the new homepage. We are continuously updating references to the new homepage and regularly improving the documentation. 
+_Simplified patch reporting_
 
-### Sample PDF
-Assuming 'AnyOrg' is the name of your organization, an exported PDF could look like this:
-<p align="left"><img src="docs/_static/example_pdf.png" width="750"/></p>
+<p align="left">
+    <img src="https://cdn.worldvectorlogo.com/logos/slack-new-logo.svg" width="16" style="vertical-align: middle; margin-right: 5px;"/>
+    Find us in the <code>#patcher</code> channel in the <a href="https://www.macadmins.org">MacAdmins Slack</a>
+</p>
+
+## What is Patcher?
+Patcher is a Command Line Interface (CLI) tool for macOS that leverages the Jamf Pro API to fetch patch management data and generates comprehensive reports in varying formats. It simplifies tracking and reporting on software update compliance across macOS devices managed through Jamf Pro.
 
-### Installation
-Install via `pip`:
+Read the full project documentation [on our project homepage](https://patcher.liquidzoo.io). 
 
-```shell
-pip install patcherctl
+## Installation
+Install releases from PyPI:
+
+```console
+$ python3 -m pip install patcherctl
 ```
+
 > [!NOTE]
 > Please note that while Patcher is installed as a package, it is meant to be used as a command line tool and not as an imported library.
 
-*Why `patcherctl?` The pip package is called patcherctl because the name patcher was already taken on PyPI. Despite this, the project itself is referred to as Patcher*
+## Sample PDF
+Assuming 'AnyOrg' is the name of your organization, an exported PDF could look like this:
+<p align="left"><img src="docs/_static/example_pdf.png" width="750"/></p>
+
+PDF Reports can be customized to fit your organizations branding needs. See the [customizing reports](https://patcher.liquidzoo.io/user/customize_reports.html) in the project docs.
+
+## Usage
+For a list of all available commands and options, visit the [usage page](https://patcher.liquidzoo.io/user/usage.html) of our documentation. 
 
-### Usage
-After installation, you can generate reports by running the main script. You can specify the output directory for the reports and choose to generate PDF reports alongside Excel files.
-```shell
-patcherctl --path '/path/to/output/directory' [--pdf]
+After installation, reports can be generated by running the `export` command. You can specify the output directory for the reports and choose to generate PDF reports alongside Excel files.
+
+```console
+$ patcherctl export --path '/path/to/output/directory' [--pdf]
 ```
 
-For a list of all available command options, visit the [usage page](https://patcher.liquidzoo.io/user/usage.html) of our documentation. 
+***
+
+## Contributing
+
+[Contributions](https://patcher.liquidzoo.io/contributing/index.html) to Patcher are welcome! We have set up templates for submitting [issues](https://github.com/liquidz00/Patcher/issues/new?template=issue.md), [feature requests](https://github.com/liquidz00/Patcher/issues/new?template=feature_request.md), and [feedback](https://github.com/liquidz00/Patcher/issues/new?template=feedback.md). Please be sure to utilize these templates when contributing to the project. 
 
-## Authors & Contributions
-Patcher is co-authored by [Andrew Speciale - @liquidz00](https://github.com/liquidz00) and [Chris Ball - @ball42](https://github.com/ball42). [Contributions](https://patcher.liquidzoo.io/contributing/index.html) to Patcher are welcome! We have set up templates for submitting issues, feature requests, and feedback. Please be sure to utilize these templates when contributing to the project.
+<!--
+Author: Andrew Lerman
+Keywords: patcher patcherctl jamf jamfpro macos patch patchmanagement apple
+-->

docs/_static/css/custom.css

@@ -59,3 +59,20 @@ div.admonition.admonition-optional > .admonition-title::after {
     color: hsl(0 0% 30%);
     content: "\f08d";
 }
+
+.patcher-banner {
+    display: block;
+    margin: 20px;
+    max-width: 720px;
+    height: auto;
+    clear: both; /* Prevent text or floated elements from wrapping */
+}
+
+html[data-theme="dark"] .patcher-banner {
+    background-color: transparent;
+}
+
+.patcher-banner + * {
+    clear: both;
+    margin-top: 20px;
+}

docs/_static/patcher-banner-readme.svg

@@ -81,8 +81,8 @@
 
 html_baseurl = "http://patcher.liquidzoo.io"
 html_theme = "pydata_sphinx_theme"
-html_logo = "_static/logo.svg"
-html_favicon = "_static/logo.svg"
+html_logo = "_static/v2-logo.svg"
+html_favicon = "_static/v2-logo-favicon.svg"
 html_static_path = ["_static"]
 html_title = f"{release}"
 
@@ -116,10 +116,15 @@
             "url": "https://pypi.org/project/patcherctl/",
             "icon": "fab fa-python",
         },
+        {
+            "name": "MacAdmins Slack",
+            "url": "https://macadmins.slack.com/archives/C07EH1R7LB0",
+            "icon": "fab fa-slack",
+        },
     ],
     "logo": {
         "text": "Patcher",
-        "image_dark": "_static/logo-dark.svg",
+        "image_dark": "_static/v2-logo-dark.svg",
     },
     "footer_start": ["copyright"],
     "footer_end": ["theme-version"],
@@ -128,6 +133,8 @@
         "**/*": ["page-toc", "sourcelink"],
     },
     "show_toc_level": 3,
+    "pygments_light_style": "xcode",
+    "pygments_dark_style": "github-dark",
 }
 
 # Remove primary sidebar from contributing page

docs/_static/v2-logo-dark.svg

@@ -5,13 +5,6 @@ Contributing
 
 Contributions to Patcher are encouraged and welcomed. Contributing does not *have* to mean writing Python code! Project documentation can always be improved and `feature requests <https://github.com/liquidz00/Patcher/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BFEATURE%5D+Your+feature+request+title>`_ can be submitted for new ideas or functionality. We, the developers of this tool, **firmly believe** that diverse backgrounds strengthen a product. Therefore, we encourage you to share your ideas and thoughts, regardless of your programming experience.
 
-Some topics we are hoping to develop in future versions of Patcher are:
-
-- **Support for other MDM vendors**; Implementing functionality for other MDM vendors (such as Kandji)
-- **Windows compatibility**; whether via Docker container or additional windows-specific credential libraries
-- **Patch analyzation**; providing information on which patch titles may need TLC above others (e.g., titles that have been released longer than 'x' amount of time that have active CVEs)
-- **Installomator support**; identifying which patch titles have an `Installomator <https://github.com/Installomator/Installomator>`_ label available to assist Admins in setting up automatic patching.
-
 How to Contribute
 -----------------
 

docs/_static/v2-logo-favicon.svg

@@ -2,21 +2,38 @@
 html_theme.sidebar_secondary.remove: True
 ---
 
-# Patcher
+```{image} _static/v2-patcher-banner-light.svg
+:class: only-light patcher-banner
+:align: center
+```
 
-*Patch reporting simplified*
+```{image} _static/v2-patcher-banner-dark.svg
+:class: only-dark patcher-banner
+:align: center
+```
 
-## Welcome to Patcher's Documentation!
+# 👋 Welcome to Patcher's Documentation!
 
 Patcher is crafted with the needs of Mac Admins in mind, offering a streamlined approach to the often complex and time-consuming task of patch management. By automating the extraction and formatting of patch data, Patcher not only saves time but also ensures accuracy and consistency in the management of software updates.
 
+*** 
+
+## Features
+
+- **Real-Time Patch Information Export**: Quickly extract up-to-date patch data for analysis.
+- **Excel Spreadsheet Integration**: Seamlessly export patch information into Excel for in-depth analysis and record-keeping.
+- **PDF Reporting**: Generate neatly formatted PDFs for easy sharing and documentation of patch statuses.
+- **Customization Options**: Tailor the tool to match your organizations branding scheme with custom fonts and logo support.
+- **Analysis**: Quickly analyze Patch Reports to identify which software titles may need some extra TLC.
+
 ::::{grid} 1 1 1 3
 :gutter: 2
 :padding: 2 2 0 0
 :class-container: sd-text-center
 
 :::{grid-item-card} {fas}`user;sd-text-primary` User Guide
 :class-card: sd-card
+:class-title: patcher-title
 :shadow: md
 :columns: 12
 
@@ -37,6 +54,7 @@ User Guide
 
 :::{grid-item-card} {fas}`book;sd-text-primary` Reference
 :class-card: sd-card
+:class-title: patcher-title
 :shadow: md
 :columns: 6
 
@@ -57,6 +75,7 @@ Reference Guide
 
 :::{grid-item-card} {fas}`hands-helping;sd-text-primary` Contributing
 :class-card: sd-card
+:class-title: patcher-title
 :shadow: md
 :columns: 6
 

docs/_static/v2-logo.svg

@@ -0,0 +1,32 @@
+:html_theme.sidebar_secondary.remove: True
+
+.. _analyzer:
+
+========
+Analyzer
+========
+
+BaseEnum
+--------
+
+.. autoclass:: patcher.client.analyze.BaseEnum
+    :members:
+
+FilterCriteria
+--------------
+
+.. autoclass:: patcher.client.analyze.FilterCriteria
+    :members:
+
+TrendCriteria
+-------------
+
+.. autoclass:: patcher.client.analyze.TrendCriteria
+    :members:
+
+Analyzer Class
+--------------
+
+.. autoclass:: patcher.client.analyze.Analyzer
+    :members:
+

docs/_static/v2-patcher-banner-dark.svg

@@ -2,54 +2,83 @@
 
 .. _cli:
 
-======================
-Command Line Interface
-======================
+============================
+Command Line Interface (CLI)
+============================
 
-.. note::
+Entry Point
+-----------
 
-    The CLI entry point collaborates with the :mod:`~patcher.client.report_manager` module. Most of the operations are managed by the Report Manager class, where debug logs are also generated, rather than within the CLI entry point.
+.. function:: cli(ctx: click.Context, debug: bool) -> None
 
-The main entry point for the Patcher CLI (patcherctl).
+    Main entry point for the CLI.
 
-Parameters
-----------
+    :param ctx: The Click context object.
+    :type ctx: click.Context
+    :param debug: Enable debug logging if `True`.
+    :type debug: :py:class:`bool`
 
-- **ctx** (*click.Context*):
-  Click context object. Used to ensure either the ``--path`` argument OR the ``--reset`` argument is supplied at runtime.
+    **Options**:
+      - ``--debug``, ``-x``: Enable verbose logging.
 
-- **path** (*AnyStr*):
-  The path to save the report(s).
+Subcommands
+-----------
 
-- **pdf** (*bool*):
-  If passed, Patcher will generate a PDF report along with the Excel spreadsheet using the :mod:`~patcher.models.reports.pdf_report` model.
+.. admonition:: Added in version 2.0
+    :class: success
 
-- **sort** (*Optional[AnyStr]*):
-  Sort patch reports by a specified column.
+    Patcher has been split into three separate commands; ``analyze``, ``reset`` and ``export``. For usage and examples, see our `Usage <usage>` page.
 
-  .. note::
-      Patcher handles the automatic conversion of the column name on your behalf. For example, if sorting by completion percent, simply pass "Completion Percent" at runtime.
+Reset Command
+^^^^^^^^^^^^^
 
-- **omit** (*bool*):
-  If passed, software titles with patches released in the last 48 hours will be omitted from the exported report(s).
+.. function:: reset(ctx: click.Context, kind: str, credential: Optional[str]) -> None
 
-- **date_format** (*AnyStr*):
-  Specify the date format for the PDF header from predefined choices. See :ref:`date format <date-format>` for more information.
+    Resets configurations based on the specified kind.
 
-- **ios** (*bool*):
-  Include the amount of enrolled mobile devices on the latest version of their respective OS. This flag uses `SOFA <https://sofa.macadmins.io>`_ to pull latest iOS versioning data.
+    **Arguments**:
+      - ``ctx``: The Click context object.
+      - ``kind``: The type of reset to perform. Options include:
 
-- **concurrency** (*int*):
-  Set the maximum concurrency level for API calls.
+        - ``full``: Resets all configurations.
+        - ``UI``: Resets only the UI configurations.
+        - ``creds``: Resets credentials.
 
-  .. danger::
-      Before using this argument, **please see** the :ref:`concurrency <concurrency>` documentation first.
+    **Options**:
+      - ``--credential``, ``-c``: Specify which credential to reset.
 
-- **debug** (*bool*):
-  Enable debug logging to see detailed debug messages. Providing this option replaces the animation usually shown to ``stdout``.
 
-- **reset** (*bool*):
-  Resets the ``config.ini`` file used for customizable elements in exported PDF reports, then triggers :func:`~patcher.client.setup._setup_ui` method. See :ref:`Customizing Reports <customize_reports>` for more information.
+Export Command
+^^^^^^^^^^^^^^
+
+.. function:: export(ctx: click.Context, path: str, pdf: bool, sort: Optional[str], omit: bool, date_format: str, ios: bool, concurrency: int) -> None
+
+    Exports patch management data in Excel and/or PDF formats.
+
+    **Arguments**:
+      - ``ctx``: The Click context object.
+      - ``path``: File path to save the generated reports.
+      - ``pdf``: Generate a PDF report if `True`.
+      - ``sort``: Column to sort by.
+      - ``omit``: Omit software titles released in the last 48 hours.
+      - ``date_format``: Format of the date in the PDF header.
+      - ``ios``: Include mobile device data if `True`.
+      - ``concurrency``: Maximum number of API requests sent concurrently.
+
+
+Analyze Command
+^^^^^^^^^^^^^^^
+
+.. function:: analyze(ctx: click.Context, excel_file: str, criteria: str, threshold: float, top_n: int, summary: bool, output_dir: Union[str, Path]) -> None
+
+    Analyzes exported patch management data.
+
+    **Arguments**:
+      - ``ctx``: The Click context object.
+      - ``excel_file``: Path to the Excel file to analyze.
+      - ``criteria``: Criteria for filtering results.
+      - ``threshold``: Threshold percentage for filtering.
+      - ``top_n``: Limit the number of results displayed.
+      - ``summary``: Generate a summary file if `True`.
+      - ``output_dir``: Directory to save the summary.
 
-- **custom_ca_file** (*Optional[AnyStr]*):
-  Pass a path to a custom Certificate Authority (CA) file for SSL verification. If provided, this file will be used in place of the default CA paths. See :ref:`ssl-verify`.

docs/_static/v2-patcher-banner-light.svg

@@ -4,11 +4,6 @@
 Config Manager
 ==============
 
-.. dropdown:: Summary
-    :icon: archive
-
-    The ``ConfigManager`` is responsible saving, updating and retrieving credentials from keychain.
-
 .. autoclass:: patcher.client.config_manager.ConfigManager
     :members:
 

docs/conf.py

@@ -0,0 +1,8 @@
+:html_theme.sidebar_secondary.remove: True
+
+=============
+Data Manager
+=============
+
+.. autoclass:: patcher.utils.data_manager.DataManager
+    :members: