Skip to content

Commit 4d43ed2

Browse files
liquidz00liquidz00
committed
Update project docs with 1.4.1 changes
1 parent 835773c commit 4d43ed2

10 files changed

+138
-144
lines changed

‎docs/conf.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
1818

1919
project = "Patcher"
20-
copyright = "2024, Andrew Speciale & Chris Ball"
20+
copyright = "2024, Andrew Lerman & Chris Ball"
2121
author = "Andrew Speciale & Chris Ball"
2222

2323
version = __version__
@@ -119,6 +119,7 @@
119119
"secondary_sidebar_items": {
120120
"**/*": ["page-toc", "sourcelink"],
121121
},
122+
"show_toc_level": 3,
122123
}
123124

124125
# Remove primary sidebar from contributing page

‎docs/reference/api_client.rst

-5
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,5 @@
44
API Client
55
==========
66

7-
.. dropdown:: Summary
8-
:icon: archive
9-
10-
The ``ApiClient`` is responsible for *most* API calls. Exceptions to this are any API calls interacting with AccessTokens, and calls made during the initial Setup.
11-
127
.. autoclass:: patcher.client.api_client.ApiClient
138
:members:

‎docs/reference/base_api_client.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:html_theme.sidebar_secondary.remove: True
2+
3+
.. _base_api_client:
4+
5+
===============
6+
Base API Client
7+
===============
8+
9+
.. autoclass:: patcher.client.__init__.BaseAPIClient
10+
:members:

‎docs/reference/decorators.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:html_theme.sidebar_secondary.remove: True
2+
3+
==========
4+
Decorators
5+
==========
6+
7+
.. automodule:: patcher.utils.decorators
8+
:members:
9+
:undoc-members:

‎docs/reference/index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ html_theme.sidebar_secondary.remove: True
77
```{toctree}
88
:caption: Client Modules
99
10+
base_api_client
1011
api_client
1112
config_manager
1213
report_manager
@@ -34,9 +35,9 @@ token
3435
:caption: Utilities
3536
3637
animation
38+
decorators
3739
exceptions
3840
logger
39-
wrappers
4041
```
4142

4243
```{toctree}

‎docs/reference/wrappers.rst

-13
This file was deleted.

‎docs/user/customize_reports.rst

+100-53
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,150 @@
11
.. _customize_reports:
22

3-
=====================
3+
====================
44
Customizing Reports
5-
=====================
5+
====================
66

77
Tailor the user interface elements of your exported PDF reports. You have the flexibility to modify the font, and customize the header and footer text according to your preferences. See the sample PDF image below for an illustration of these customizable features.
88

99
.. _example-pdf-image:
1010

11-
.. image:: https://raw.githubusercontent.com/liquidz00/Patcher/develop/images/example_pdf.jpeg
11+
.. image:: ../_static/example_pdf.jpeg
1212
:alt: Example PDF
1313
:width: 750px
1414
:align: center
1515

1616
.. seealso::
1717
Configuring the date format is done at runtime by using the ``--date-format`` option. See :ref:`date format <date-format>` for more information.
1818

19-
.. _config_ini:
19+
.. _property_list_file:
2020

2121
Setup
22-
-----
22+
=====
2323

24-
When you first launch Patcher, a :ref:`setup assistant <setup>` will automatically create the necessary ``config.ini`` file and copy the required fonts to the appropriate directory.
24+
When you first launch Patcher, a :ref:`setup assistant <setup>` will automatically create the necessary ``com.liquidzoo.patcher.plist`` file in the user's Library Application Support directory, located at ``$HOME/Library/Application Support/Patcher``. Once setup is completed successfully, the ``first_run_done`` key in the property list file will automatically be set to ``True``:
2525

26-
Modifying the file
27-
^^^^^^^^^^^^^^^^^^
26+
.. code-block:: xml
2827
29-
Any resource Patcher interacts with can be found in the Application Support directory in the user library. Using ``jappleseed`` as an example, the path to the configuration file would be ``'/Users/jappleseed/Library/Application Support/Patcher/config.ini'``.
28+
<?xml version="1.0" encoding="UTF-8"?>
29+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
30+
<plist version="1.0">
31+
<dict>
32+
<key>Setup</key>
33+
<dict>
34+
<key>first_run_done</key>
35+
<true/>
36+
</dict>
37+
</dict>
38+
</plist>
3039
31-
Open this file in your text editor of choice, or execute the command below in Terminal to open the file in the TextEdit app.
40+
.. admonition:: Warning
41+
:class: warning
3242

33-
.. code-block:: console
43+
**Do not modify** the ``first_run_done`` key in the ``Setup`` dictionary directly. Altering this key may cause Patcher to re-run the setup process. If you need to reset the initial setup state, use the ``--reset`` option instead. For more information, see :ref:`resetting Patcher <resetting_patcher>`.
3444

35-
$ open -a "TextEdit.app" ~/Library/Application\ Support/Patcher/config.ini
45+
Modifying the Property List File
46+
================================
3647

37-
Sample configuration
38-
^^^^^^^^^^^^^^^^^^^^
48+
The property list file contains the settings that control the appearance of the PDF reports. You can edit these values using ``/usr/libexec/PlistBuddy`` or a code editor of your choice (VSCode, BBEdit, CodeRunner, etc.).
3949

40-
Still assuming the logged in user is jappleseed, a ``config.ini`` file could look like the following:
50+
.. admonition:: Opening Property Lists in Xcode
51+
:class: tip
4152

42-
.. code-block:: ini
53+
If the plist file appears as a binary file when opened in VSCode or other editors, you can open it in **Xcode** instead. Xcode is available as a free download from the Mac App Store and fully supports editing plist files. This will prevent issues with binary formatting that some editors may encounter.
4354

44-
[Settings]
45-
patcher_path = /Users/jappleseed/Library/Application Support/Patcher
55+
Using ``jappleseed`` as an example, the path to the property list file would be:
4656

47-
[UI]
48-
header_text = AnyOrg Mac Patch Report
49-
footer_text = AnyOrg Mac Patch Report
50-
font_name = Assistant
51-
font_regular_path = /Users/jappleseed/Library/Application Support/Patcher/fonts/Assistant-Regular.ttf
52-
font_bold_path = /Users/jappleseed/Library/Application Support/Patcher/fonts/Assistant-Bold.ttf
57+
``/Users/jappleseed/Library/Application Support/Patcher/com.liquidzoo.patcher.plist``
5358

54-
The above example would result in a PDF report that looks identical to the :ref:`example PDF image <example-pdf-image>` at the top of this page.
59+
Editing the Header & Footer Text
60+
--------------------------------
5561

56-
.. warning::
57-
Altering the ``[Settings]`` section of the configuration file is not recommended. Patcher references this path throughout the codebase and modifying it incorrectly may lead to unintended results or errors.
62+
.. tip::
63+
Why not use ``defaults`` to edit the property list file? Unfortunately, the ``defaults`` binary in macOS lacks the ability to update keys nested within dictionaries. ``PlistBuddy`` is much better equipped to handle property lists with nested elements.
5864

59-
Edit Header and Footer Text
60-
---------------------------
65+
To modify the header and footer text using PlistBuddy, use the following commands:
6166

62-
To customize the header and footer texts, simply modify the ``header_text`` and ``footer_text`` values under the UI section of the config file.
67+
.. code-block:: console
6368
64-
.. code-block:: ini
69+
$ /usr/libexec/PlistBuddy -c "Set :UI:HEADER_TEXT 'Your Custom Header Text'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
70+
$ /usr/libexec/PlistBuddy -c "Set :UI:FOOTER_TEXT 'Your Custom Footer Text'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
6571
66-
[UI]
67-
header_text = Your Custom Header Text
68-
footer_text = Your Custom Footer Text
72+
These commands will correctly update the ``HEADER_TEXT`` and ``FOOTER_TEXT`` keys within the ``UI`` dictionary.
6973

7074
.. note::
7175
The footer text will automatically append a ``|`` character followed by the page number to the end of the specified footer text.
7276

77+
Sample Property List Structure
78+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
79+
80+
Below is an example of what the nested UI dictionary might look like in the property list file:
81+
82+
.. code-block:: xml
83+
84+
<?xml version="1.0" encoding="UTF-8"?>
85+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
86+
<plist version="1.0">
87+
<dict>
88+
<key>UI</key>
89+
<dict>
90+
<key>HEADER_TEXT</key>
91+
<string>AnyOrg Patch Report</string>
92+
<key>FOOTER_TEXT</key>
93+
<string>AnyOrg Patch Report</string>
94+
<key>FONT_NAME</key>
95+
<string>Assistant</string>
96+
<key>FONT_REGULAR_PATH</key>
97+
<string>/Users/jappleseed/Library/Application Support/Patcher/fonts/Assistant-Regular.ttf</string>
98+
<key>FONT_BOLD_PATH</key>
99+
<string>/Users/jappleseed/Library/Application Support/Patcher/fonts/Assistant-Bold.ttf</string>
100+
</dict>
101+
</dict>
102+
</plist>
103+
104+
The above example would result in a PDF report that looks identical to the :ref:`example PDF image <example-pdf-image>` at the top of this page.
105+
73106
Customizing the Font
74107
--------------------
75108

76-
If you wish to change the font, modify the ``font_name``, ``font_regular_path`` and ``font_bold_path`` values in the UI section:
109+
To change the font, update the ``FONT_NAME``, ``FONT_REGULAR_PATH`` and ``FONT_BOLD_PATH`` values in the UI dictionary.
77110

78-
.. code-block:: ini
111+
.. code-block:: console
79112
80-
[UI]
81-
font_name = YourPreferredFont
82-
font_regular_path = /path/to/your/font/Regular.ttf
83-
font_bold_path = /path/to/your/font/Bold.ttf
113+
$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_NAME 'Helvetica'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
114+
$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_REGULAR_PATH '/path/to/Helvetica-Regular.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
115+
$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_BOLD_PATH '/path/to/Helvetica-Bold.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
84116
85117
.. important::
86118
The default font used in testing is `Google's Assistant Font <https://fonts.google.com/specimen/Assistant>`_. While you can specify a different font to match your organization's branding, be aware that doing so may cause formatting or alignment issues in the exported PDF reports. It is recommended to test the PDF export functionality thoroughly after changing the font to ensure the new font does not adversely affect the document's appearance.
87119

88120
Full Example Configuration
89121
--------------------------
90122

91-
A full example configuration with custom header, footer text and a specified font:
92-
93-
.. code-block:: ini
94-
95-
[Settings]
96-
patcher_path = /Users/$user/Library/Application Support/Patcher
97-
98-
[UI]
99-
header_text = Confidential Report
100-
footer_text = © 2024 Your Company
101-
font_name = Helvetica
102-
font_regular_path = /path/to/Helvetica-Regular.ttf
103-
font_bold_path = /path/to/Helvetica-Bold.ttf
123+
Here is an example configuration with custom header, footer text, and a specified font:
124+
125+
.. code-block:: xml
126+
127+
<?xml version="1.0" encoding="UTF-8"?>
128+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
129+
<plist version="1.0">
130+
<dict>
131+
<key>Setup</key>
132+
<dict>
133+
<key>first_run_done</key>
134+
<true/>
135+
</dict>
136+
<key>UI</key>
137+
<dict>
138+
<key>HEADER_TEXT</key>
139+
<string>Confidential Report</string>
140+
<key>FOOTER_TEXT</key>
141+
<string>© 2024 Your Company</string>
142+
<key>FONT_NAME</key>
143+
<string>Helvetica</string>
144+
<key>FONT_REGULAR_PATH</key>
145+
<string>/path/to/Helvetica-Regular.ttf</string>
146+
<key>FONT_BOLD_PATH</key>
147+
<string>/path/to/Helvetica-Bold.ttf</string>
148+
</dict>
149+
</dict>
150+
</plist>

‎docs/user/install.md

+6-59
Original file line numberDiff line numberDiff line change
@@ -59,69 +59,16 @@ Options:
5959
```
6060

6161
(ssl-verify)=
62-
## SSL Verification and Self-Signed Certificates
62+
## SSL Verification
6363

64-
When using Patcher, you may encounter SSL verification issues, particularly if your network environment uses self-signed certificates or custom Certificate Authorities (CAs). Patcher uses both the `aiohttp` and `urllib` libraries to make API calls.
64+
As of version 1.4.1, Patcher no longer modifies SSL configurations. SSL handling for custom certificates required some additional TLC by end users and would often cause SSL verification errors at runtime. This is compounded when taking into account our end users are likely on managed systems with security policies and third-party certificates (e.g., Zscaler).
6565

66-
:::{versionadded} 1.3.5
67-
A certificate file can be passed to Patcher with the `--custom-ca-file` option.
68-
See {ref}`custom-ca` for more information.
69-
:::
70-
71-
### Configure macOS to Trust Custom Certificates
72-
73-
If you are on a managed host, chances are this has already been done for you as part of being enrolled with an MDM. However, it never hurts to verify.
74-
75-
1. Open the Keychain application in `/Applications/Utilities/Keychain Access.app`
76-
2. Click **System** on the left sidebar underneath *System Keychains*, and select the **Certificates** tab
77-
3. Locate the Certificate in question and double-click to open it
78-
4. Set the certificate to "Always Trust" under the Trust section
79-
80-
#### Exporting the Certificate
81-
82-
Alternatively, you may need to export the certificate in `.pem` format. If so, export the certificate from Keychain by right-clicking and selecting **Export** from the dialog menu. Be sure to select the file format as `.pem` when exporting.
83-
84-
### Adding Custom Certificates
66+
With the current version, SSL handling is no longer required by the end user. We've integrated ``curl`` with ``asyncio`` within Patcher's functionality to automatically handle SSL verification as part of API requests. This design choice removes the need for manual SSL configurations, streamlining the setup for MacAdmins on managed computers.
8567

86-
Patcher uses both `aiohttp` and `urllib` to make API requests. Both libraries rely on Python's built-in `ssl` module to handle SSL certificates. On macOS, Python *typically* uses the system's SSL certificate store or the certificates bundled with Python itself.
87-
88-
:::{attention}
89-
The following steps will likely need local administrator privileges (`sudo`).
90-
:::
91-
92-
#### Identify the Certificate Path
93-
94-
First, determine where Python is currently looking for certificates. You can find this by using the `ssl` module in Python.
95-
96-
::::{tab-set}
97-
98-
:::{tab-item} Command Prompt
99-
```console
100-
$ python3 -c "import ssl; print(ssl.get_default_verify_paths())"
101-
```
102-
:::
103-
104-
:::{tab-item} Python
105-
```python
106-
import ssl
107-
108-
# Print default SSL certificate paths
109-
print(ssl.get_default_verify_paths())
110-
```
68+
:::{note}
69+
While the current integration between `curl` and `asyncio` gets the job done for handling SSL verification, there's room for refinement. Community contributions to enhance this functionality are welcome and encouraged. If you're interested in exploring ways to solidify this process further, check out the relevant code in the {ref}`BaseAPIClient <base_api_client>` class.
11170
:::
11271

113-
::::
114-
115-
The command will output paths where Python looks for certificates, usually pointing to a `cert.pem` file or similar. Be sure to notate the proper path before proceeding.
116-
117-
#### Add the Self-Signed Certificate
118-
119-
If not completed already, [export](#exporting-the-certificate) the certificate to a file location of your choosing. The certificate can then be added to the default bundle with the following command:
120-
121-
```console
122-
$ cat /path/to/exported/certificate.pem >> /path/to/default/certificate/location/cert.pem
123-
```
124-
125-
If permission errors are thrown, attempt the command again with `sudo`.
72+
This update makes it easier for Patcher to run smoothly in secure environments, without the hassle of adjusting system certificates or tinkering with Python’s SSL settings.
12673

12774
**If none of the above steps worked to resolve the issue**, please reach out to us and let us know what (if any) security software is installed on your machine. This will help us troubleshoot issues in the future. Additionally, get in touch with someone from your security team for next steps as they may have a solution in place.

‎docs/user/prereqs.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,8 @@ Ensure you have the following before proceeding with the installation and setup
55
- **Python 3.10 or Higher**: Make sure Python is installed on your system. You can download it from [python.org](https://www.python.org/downloads/).
66
- **Access to a Jamf Pro Instance**: You need an instance of Jamf Pro with administrator privileges to perform setup tasks.
77

8-
:::{important}
9-
**For versions 1.3.4 and later**: Patcher can automatically handle the creation of API clients and roles, provided [SSO is not used for Jamf Pro accounts](https://developer.jamf.com/jamf-pro/docs/jamf-pro-api-overview#authentication-and-authorization).
10-
11-
If SSO is used, you can either manually create an API Role & Client, *or* you can create a standard user account with admin privileges to pass to the setup assistant.
8+
:::{versionadded} 1.3.5
9+
Patcher can automatically handle the creation of API clients and roles, provided [SSO is not used for Jamf Pro accounts](https://developer.jamf.com/jamf-pro/docs/jamf-pro-api-overview#authentication-and-authorization). If SSO is used, you can either manually create an API Role & Client, *or* you can create a standard user account with admin privileges to pass to the setup assistant.
1210
:::
1311

1412
## Handling SSO in Jamf Pro
@@ -37,7 +35,5 @@ If your Jamf Pro environment uses Single Sign-On (SSO), follow the instructions
3735
- After setup has completed, delete the temporary account to maintain security standards.
3836

3937
:::{seealso}
40-
:class: dropdown
41-
4238
Refer to the [Jamf Pro Documentation](https://learn.jamf.com/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html) on API Roles and Clients for more information on creating roles and clients.
4339
:::

0 commit comments

Comments
 (0)