DOC: doc update

updating docs - remove mention of enums in user-docs to favor strings - makes it easier to use

docs/developer_docs/ADDING_NEW_PRESETS.md

@@ -1,6 +1,6 @@
 # Adding New Preset To An Existing Preset Group
 
-## **1. Add the preset name to the corresponding enum class in `/lib/enums/query/query_presets.py`**
+## **1. Add the preset name to the corresponding enum class in `openstackquery/enums/query_presets.py`**
 
 e.g.
 ```python
@@ -16,7 +16,7 @@ class QueryPresetsGeneric(QueryPresets):
 
 (Optional) Add alias mappings for the preset - see [Adding Aliases](ADDING_ALIASES.md)
 
-## **2. Edit the corresponding handler class in `/lib/openstack_query/handlers/client_side_handler_<preset-group>.py`.**
+## **2. Edit the corresponding handler class in `/openstackquery/handlers/client_side_handler_<preset-group>.py`.**
 
 Here you must:
 - add a 'client-side' filter function as a method
@@ -67,9 +67,9 @@ Here you must:
 1. Evaluate which Query class should be able to use your new preset
 2. For each Query class you've chosen, evaluate which property(ies) the preset should work on
 3. Add chosen mappings to `get_client_side_handlers` method in the Mappings class for each chosen Query
-   - these are located in `mappings/<query-resource>_mapping.py`
+   - these are located in `openstackquery/mappings/<query-resource>_mapping.py`
 
-e.g. Adding Mappings for `QueryPresetsGeneric.NEW_PRESET` to `ServerQuery`. Editing `mappings/server_mapping.py`
+e.g. Adding Mappings for `QueryPresetsGeneric.NEW_PRESET` to `ServerQuery`. Editing `openstackquery/mappings/server_mapping.py`
 ```python
 
 class ServerMapping(MappingInterface):
@@ -131,19 +131,19 @@ class ServerMapping(MappingInterface):
 As stated above - presets are grouped based on the datatype of the property the act on. If you need another preset
 group - you can add one like so:
 
-1. Create a new preset group class in `/lib/enums/query/query_presets.py`
+1. Create a new preset group class in `openstackquery/enums/query_presets.py`
     - it inherits from base class QueryPresets
 
 
-2. Create new client side handler in `/lib/openstack_query/handlers/client_side_handler_<preset>.py`
-   - it inherits from base class `ClientSideHandler` - `/lib/openstack_query/handlers/client_side_handler.py`.
+2. Create new client side handler in `/openstackquery/handlers/client_side_handler_<preset>.py`
+   - it inherits from base class `ClientSideHandler` - `/openstackquery/handlers/client_side_handler.py`.
 
 
 3. Add your preset as a attribute in query_client_side_handlers dataclass
-   - located in `/lib/structs/query/query_client_side_handlers.py`
+   - located in `/openstackquery/structs/query_client_side_handlers.py`
 
 
 4. Follow steps mentioned above to add new presets to the new preset group class you've created
 
-5. Edit `QueryPresets` type declaration at the bottom of the file `/lib/enums/query/query_presets.py` and add your new
-preset ffclass to it
+5. Edit `QueryPresets` type declaration at the bottom of the file `/openstackquery/enums/query_presets.py` and add your new
+preset class to it

docs/developer_docs/ADDING_NEW_QUERIES.md

@@ -7,7 +7,7 @@ A new subclass of the `PropEnum` class is required to store valid property enums
 resource. To do this, you must:
 1. Identify all available properties for the new query.
    - You can find this information by looking in the openstacksdk api documentation [here](https://docs.openstack.org/openstacksdk/latest/user/index.html#api-documentation).
-2. Create a new file under `/enums/query/props/` called `<resource>_properties.py`, replace `<resource>` with the name of the openstack resource you want to query
+2. Create a new file under `/enums/` called `<resource>_properties.py`, replace `<resource>` with the name of the openstack resource you want to query
 3. Create the `<resource>Properties` class definition
    - class must inherit from `PropEnum` abstract base class and implement abstract methods.
 
@@ -49,7 +49,7 @@ A new subclass of the `RunnerWrapper` class is required to store how to actually
 will also be the place where we can define extra parameters that can be used to fine-tune the query.
 
 To add a Runner Class:
-1. Create a new file under `/openstack_query/runners/` called `<resource>_runner.py` replace `<resource>` with openstack resource name you want to query
+1. Create a new file under `/openstackquery/runners/` called `<resource>_runner.py` replace `<resource>` with openstack resource name you want to query
 2.  Create the `<resource>Runner` class definition
    - class must inherit from `RunnerWrapper` abstract base class and implement abstract methods.
 
@@ -116,10 +116,10 @@ see `runners/server_runner.py` to see the implementation details.
 A new subclass of the `MappingInterface` class is required to store query mappings.
 
 To add a Mapping Class:
-1. Create a new file under `/openstack_query/mappings/` called `<resource>_mapping.py` replace `<resource>` with openstack resource name you want to query
+1. Create a new file under `/openstackquery/mappings/` called `<resource>_mapping.py` replace `<resource>` with openstack resource name you want to query
 2.  Create the `<resource>Mapping` class definition
    - class must inherit from `MappingInterface` abstract base class and implement abstract methods.
-3. Update the enum holding query types `/enums/query/query_types.py` and add a Enum mapping to this Mapping class.
+3. Update the enum holding query types `/enums/query_types.py` and add a Enum mapping to this Mapping class.
 4. (Optional) Add alias mappings for the query type - see [Adding Aliases](ADDING_ALIASES.md)
 
 ### 3a. Set the Prop Enum class
@@ -232,7 +232,7 @@ To add a server-side filter you must:
 Now that the functionality has been added, you can make it available by creating a function in `query_objects` which
 will call `QueryFactory` with the `ResourceMapping` class we just created.
 
-e.g. Add this function to `openstack_query/api/query_objects.py` (as usual, replace `Resource` with the name of the openstack resource your querying)
+e.g. Add this function to `openstackquery/api/query_objects.py` (as usual, replace `Resource` with the name of the openstack resource your querying)
 ```python
 def ResourceQuery() -> QueryAPI:
    """
@@ -243,7 +243,7 @@ def ResourceQuery() -> QueryAPI:
 
 ```
 
-Then add this import to the top-level `__init__.py` - in `openstack_query/__init__.py`
+Then add this import to the top-level `__init__.py` - in `openstackquery/__init__.py`
 ```python
 from .api.query_objects import ResourceQuery
 ```

docs/developer_docs/OTHER_WORKFLOWS.md

@@ -4,50 +4,46 @@ This file contains other workflows/instructions for adding new parts to the quer
 ## Adding a property related to an existing resource
 
 To add or alter a property, locate the enum class holding property mappings for the specific resource you want to change.
-(Usually `enums/props/<resource>_properties.py`)
+(Usually `openstackquery/enums/<resource>_properties.py`)
 
 Add a new mapping like so (Adding a new property to `ServerProperties`:
 
 ```python
-
 class ServerProperties(PropEnum):
     ...
 
     FLAVOR_ID = auto()
     ...
     NEW_PROP = auto() # This Adds a new enum value to represent you new property
 
+    @staticmethod
+    def get_prop_mapping(prop):
     ...
-
-     @staticmethod
-        def get_prop_mapping(prop):
+    mapping = {
         ...
-        mapping = {
-            ...
-            # This adds a mapping from enum to a anonymous lambda function which will take an Openstack Server object
-            # and get the value for `NEW_PROP`
-            ServerProperties.NEW_PROP: lambda a: a["new_prop"]
-
-            # You can also write the function to get the property as a method in the Class
-            # and map your enum to that - like we did for ADDRESSES
-            ServerProperties.ADDRESSES: ServerProperties.get_ips,
-        }
+        # This adds a mapping from enum to a anonymous lambda function which will take an Openstack Server object
+        # and get the value for `NEW_PROP`
+        ServerProperties.NEW_PROP: lambda a: a["new_prop"],
+
+        # You can also write the function to get the property as a method in the Class
+        # and map your enum to that - like we did for ADDRESSES
+        ServerProperties.ADDRESSES: ServerProperties.get_ips,
+    }
 ```
 
 ## Adding a meta-param to an existing Runner class
 
 Runners refer to the class that is responsible for actually running the query.
 Each Query has an associated Runner Class and inherits from `MappingInterface`.
-- located in `openstack_query/runners/<resource>_runner` - replace `<resource>` with the resource name you want to change - i.e. `server`
+- located in `openstackquery/runners/<resource>_runner` - replace `<resource>` with the resource name you want to change - i.e. `server`
 
 
 If you want to add meta-param functionality, it's a good idea to check whether it can be done already by using
 the API commands provided - i.e. `where()`, `sort_by()`, `group_by()`.
 
 We favor using the API rather than meta-params since they are harder to document well and could be confusing
 
-
-To add a metaparam you need to locate the runner class associated for the resource you want to change.
+To add a meta-param you need to locate the runner class associated for the resource you want to change.
 
 Then edit the `_parse_meta_params` method
 
@@ -62,8 +58,8 @@ def _parse_meta_params(
 
 ```
 
-**NOTE: when editing an existing query's meta-params - YOU MUST MAKE SURE THE NEW PARAM IS OPTIONAL - so as to not break other already existing workflows**
-    - you can do this by providing a default value.
+**NOTE: when editing an existing query's meta-params - YOU MUST MAKE SURE THE NEW PARAM IS OPTIONAL**
+So as to not break other already existing workflows - you can do this by providing a default value.
 
 The `_parse_meta_params` method returns a dictionary that can be ultimately merged with server-side key-word arguments in the `run_query` method.
 This new dictionary can then be passed to the openstacksdk call.

docs/developer_docs/OVERVIEW.md

@@ -12,13 +12,15 @@
 
 ## Overview
 
-The Query Library is broken up into 3 main parts.
+The Query Library is broken up into 4 main parts.
 - Query Blocks
   - which contain actual query logic split up into different parts - builder, executer, etc.
 - Mappings
   - contains info that is specific to the query, used to setup query blocks
 - API
   - exposes API methods to the user
+- Runners
+  - which define how to actually run the query
 
 The image below shows how these components relate to each other when invoking a query object via API
 
@@ -29,7 +31,7 @@ The image below shows how these components relate to each other when invoking a
 
 Query Blocks contain the generic logic of setting up, running and outputting the query results.
 Each Query Block is instantiated and set up using mappings.
-Query block files are located in `openstack_query/query_blocks/` submodule
+Query block files are located in `openstackquery/query_blocks/` submodule
 
 Query Blocks are written so they don't need to be edited when a new feature needs to be written.
 As a developer, you likely won't need to worry about them unless you are fixing bugs/refactoring
@@ -42,7 +44,7 @@ These class sets up the following:
    - and how to get those values from the equivalent Openstack object
  - what preset-property pairs are valid for `where()` calls.
  - what shared common properties (if any) are available between this resource and other resources - for chaining
- - how to actually run the query using openstacksdk
+ - map the query to the corresponding "runner" class
 
 Each Query has a corresponding file called `<name_of_resource>_mapping`. The files is located in `/lib/openstack_query/mappings/`
 This file is used to configure the above.
@@ -57,7 +59,8 @@ with openstack.
 The API must be unchanging - as a developer you will not need to interact with this file unless you are adding a new
 API method - e.g. adding a new way to output results
 
-**NOTE: Deleting or Altering a API method requires approval and a good reason since it may break existing workflows**
+**NOTE: Deleting or Altering an API method requires approval from maintainers and a good reason since it may break
+existing workflows**
 
 
 ### Client-Side Filters vs Server-Side Filters