feat(FirewallProxy)!: add a constructor (#119)

Makefile

@@ -1,21 +1,28 @@
+.phony: lint
 lint:
 	flake8 panos_upgrade_assurance tests
 
+.phony: security
 security:
 	bandit -c pyproject.toml -r .
 
+.phony: format_check
 format_check:
 	black --diff --check panos_upgrade_assurance tests
 
+.phony: format
 format:
 	black panos_upgrade_assurance tests
 
+.phony: test_coverage
 test_coverage:
 	pytest --cov panos_upgrade_assurance --cov-report=term-missing --cov-report=xml:coverage.xml
 
+.phony: documentation
 documentation:
 	pydoc-markdown
 
+.phony: check_line_length
 check_line_length:
 	@for FILE in $$(find . -type f -name '*.py'); do \
 		echo $$FILE; \
@@ -29,4 +36,8 @@ check_line_length:
 		done < "$$FILE"; \
 	done
 
+.phony: all
 all: lint format security test_coverage documentation
+
+.phony: sca
+sca: format lint security

docs/panos-upgrade-assurance/api/exceptions.md

@@ -28,6 +28,11 @@ module.
 
 Parent class for all exceptions coming from [Utils](/panos/docs/panos-upgrade-assurance/api/utils) module.
 
+## class `WrongNumberOfArgumentsException`
+
+Thrown when [FirewallProxy](/panos/docs/panos-upgrade-assurance/api/firewall_proxy) constructor is given wrong number or
+set of arguments.
+
 ## class `CommandRunFailedException`
 
 Used when a command run on a device does not return the `success` status.

docs/panos-upgrade-assurance/api/firewall_proxy.md

@@ -7,21 +7,73 @@ custom_edit_url: null
 ---
 ## class `FirewallProxy`
 
-Class representing a Firewall.
+A proxy to the [Firewall][fw] class.
 
-Proxy in this class means that it is between the *high level*
-[`CheckFirewall`](/panos/docs/panos-upgrade-assurance/api/check_firewall#class-checkfirewall) class and a device itself.
-Inherits the [Firewall][fw] class but adds methods to interpret XML API commands. The class constructor is also inherited
-from the [Firewall][fw] class.
+Proxy in this case means that this class is between the *high level*
+[`CheckFirewall`](/panos/docs/panos-upgrade-assurance/api/check_firewall#class-checkfirewall) class and the
+[`Firewall`][fw] class representing the device itself.
+There is no inheritance between the [`Firewall`][fw] and [`FirewallProxy`][fwp] classes, but an object of the latter one
+has access to all attributes of the former.
 
 All interaction with a device are read-only. Therefore, a less privileged user can be used.
 
-All methods starting with `is_` check the state, they do not present any data besides simple `boolean`values.
+All methods starting with `is_` check the state, they do not present any data besides simple `boolean` values.
 
 All methods starting with `get_` fetch data from a device by running a command and parsing the output.
 The return data type can be different depending on what kind of information is returned from a device.
 
 [fw]: https://pan-os-python.readthedocs.io/en/latest/module-firewall.html#module-panos.firewall
+[fwp]: /panos/docs/panos-upgrade-assurance/api/firewall_proxy
+
+__Attributes__
+
+
+- `_fw (Firewall)`: an object of the [`Firewall`][fw] class.
+
+### `FirewallProxy.__init__`
+
+```python
+def __init__(firewall: Optional[Firewall] = None, **kwargs)
+```
+
+Constructor of the [`FirewallProxy`][fwp] class.
+
+Main purpose of this constructor is to store an object of the [`Firewall`][fw] class. This can be done in two ways:
+
+1. by passing an existing object
+1. by passing credentials and address of a device (all parameters used byt the [`Firewall`][fw] class constructor
+    are supported).
+
+:::tip
+Please note that positional arguments are not supported.
+:::
+
+__Parameters__
+
+
+- __firewall__ (`Firewall`): An existing object of the [`Firewall`][fw] class.
+- __**kwargs__: Used to pass keyword arguments that will be used directly in the [`Firewall`][fw] class constructor.
+
+__Raises__
+
+
+- `WrongNumberOfArgumentsException`: Raised when a mixture of arguments is passed (for example a [`Firewall`][fw]
+    object and firewall credentials).
+
+### `FirewallProxy.__getattr__`
+
+```python
+def __getattr__(attr)
+```
+
+An overload of the default `__getattr__()` method.
+
+Its main purpose is to provide backwards compatibility to the old [`FirewallProxy`][fwp] class structure. It's called
+when a requested attribute does not exist in the [`FirewallProxy`][fwp] class object, and it tries to fetch it
+from the [`Firewall`][fw] object stored within the [`FirewallProxy`][fwp] object.
+
+From the [`FirewallProxy`][fwp] object's interface perspective, this provides the same behaviour as if the
+[`FirewallProxy`][fwp] would still inherit from the [`Firewall`][fw] class.
 
 ### `FirewallProxy.op_parser`
 

docs/panos-upgrade-assurance/configuration_details.mdx

@@ -71,7 +71,7 @@ Elements of this list can be either of the `str` or `dict` type:
 
   ```mdx-code-block
   </TabItem>
-  <TabItem value="ansible" label="YAML" default>
+  <TabItem value="ansible" label="YAML">
   ```
 
   ```yaml
@@ -106,7 +106,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml
@@ -151,7 +151,7 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
 
     ```mdx-code-block
     </TabItem>
-    <TabItem value="ansible" label="YAML" default>
+    <TabItem value="ansible" label="YAML">
     ```
 
     ```yaml
@@ -187,7 +187,7 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
 
     ```mdx-code-block
     </TabItem>
-    <TabItem value="ansible" label="YAML" default>
+    <TabItem value="ansible" label="YAML">
     ```
 
     ```yaml
@@ -223,7 +223,7 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
 
   ```mdx-code-block
   </TabItem>
-  <TabItem value="ansible" label="YAML" default>
+  <TabItem value="ansible" label="YAML">
   ```
 
   ```yaml
@@ -290,7 +290,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml
@@ -382,7 +382,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers title="Lookup limited to a single interface"
@@ -457,7 +457,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -510,7 +510,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -561,7 +561,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -607,7 +607,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -652,7 +652,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -700,7 +700,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -746,7 +746,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -816,7 +816,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -865,7 +865,7 @@ checks_configuration = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml
@@ -971,7 +971,7 @@ snapshots_config = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1076,7 +1076,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1154,7 +1154,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1214,7 +1214,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1267,7 +1267,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1319,7 +1319,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1377,7 +1377,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers
@@ -1433,7 +1433,7 @@ reports = [
 
 ```mdx-code-block
 </TabItem>
-<TabItem value="ansible" label="YAML" default>
+<TabItem value="ansible" label="YAML">
 ```
 
 ```yaml showLineNumbers

panos_upgrade_assurance/__init__.py

@@ -0,0 +1,3 @@
+from importlib import metadata
+
+__version__ = metadata.version(__package__)

panos_upgrade_assurance/exceptions.py

@@ -31,6 +31,14 @@ class UtilsException(Exception):
     pass
 
 
+class WrongNumberOfArgumentsException(FirewallProxyException):
+    """Thrown when [FirewallProxy](/panos/docs/panos-upgrade-assurance/api/firewall_proxy) constructor is given wrong number or
+    set of arguments.
+    """
+
+    pass
+
+
 class CommandRunFailedException(FirewallProxyException):
     """Used when a command run on a device does not return the `success` status."""