diff --git a/docs/developer_docs/ADDING_NEW_PRESETS.md b/docs/developer_docs/ADDING_NEW_PRESETS.md index bef0908..d1b2e73 100644 --- a/docs/developer_docs/ADDING_NEW_PRESETS.md +++ b/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_.py`.** +## **2. Edit the corresponding handler class in `/openstackquery/handlers/client_side_handler_.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/_mapping.py` + - these are located in `openstackquery/mappings/_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_.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_.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 diff --git a/docs/developer_docs/ADDING_NEW_QUERIES.md b/docs/developer_docs/ADDING_NEW_QUERIES.md index d44c5eb..f9a8071 100644 --- a/docs/developer_docs/ADDING_NEW_QUERIES.md +++ b/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 `_properties.py`, replace `` with the name of the openstack resource you want to query +2. Create a new file under `openstackquery/enums/props/` called `_properties.py`, replace `` with the name of the openstack resource you want to query 3. Create the `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 `_runner.py` replace `` with openstack resource name you want to query +1. Create a new file under `/openstackquery/runners/` called `_runner.py` replace `` with openstack resource name you want to query 2. Create the `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 `_mapping.py` replace `` with openstack resource name you want to query +1. Create a new file under `/openstackquery/mappings/` called `_mapping.py` replace `` with openstack resource name you want to query 2. Create the `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 ``` @@ -251,8 +251,6 @@ from .api.query_objects import ResourceQuery Now you can use the new functionality like so ```python -from enums.query.props.resource_properties import ResourceProperties -from openstack_query import ResourceQuery - -ResourceQuery().where(...).select(ResourceProperties.PROP_1).run("prod", meta_param1="abc", meta_param2="def") +from openstackquery import ResourceQuery +ResourceQuery().where(...).select("prop_1").run("prod", meta_param1="abc", meta_param2="def") ``` diff --git a/docs/developer_docs/OTHER_WORKFLOWS.md b/docs/developer_docs/OTHER_WORKFLOWS.md index 298c08f..288609a 100644 --- a/docs/developer_docs/OTHER_WORKFLOWS.md +++ b/docs/developer_docs/OTHER_WORKFLOWS.md @@ -4,12 +4,11 @@ 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/_properties.py`) +(Usually `openstackquery/enums/_properties.py`) Add a new mapping like so (Adding a new property to `ServerProperties`: ```python - class ServerProperties(PropEnum): ... @@ -17,28 +16,26 @@ class ServerProperties(PropEnum): ... 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/_runner` - replace `` with the resource name you want to change - i.e. `server` +- located in `openstackquery/runners/_runner` - replace `` 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 @@ -46,8 +43,7 @@ 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. diff --git a/docs/developer_docs/OVERVIEW.md b/docs/developer_docs/OVERVIEW.md index db2c1e7..768b55d 100644 --- a/docs/developer_docs/OVERVIEW.md +++ b/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,9 +44,9 @@ 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 `_mapping`. The files is located in `/lib/openstack_query/mappings/` +Each Query has a corresponding file called `_mapping`. The files is located in `openstackquery/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 diff --git a/docs/user_docs/API.md b/docs/user_docs/API.md index 5f6dafa..93e720b 100644 --- a/docs/user_docs/API.md +++ b/docs/user_docs/API.md @@ -11,12 +11,13 @@ The query library currently supports queries on the following Openstack resource **NOTE**: In development - more query options will be added -| Openstack Resource | Description | Reference for Query Object | How to Import | -|----------------------------------------------------------------------------------------------------------|----------------------------------------|---------------------------------------|--------------------------------------------| -| [Servers](https://docs.openstack.org/api-ref/compute/#servers-servers) | Run a Query on Openstack Servers (VMs) | [SERVERS.md](query_docs/SERVERS.md) | `from openstack_query import ServerQuery` | -| [Users](https://docs.openstack.org/api-ref/identity/v3/index.html?expanded=list-users-detail#users) | Run a Query on Openstack Users | [USERS.md](query_docs/USERS.md) | `from openstack_query import UserQuery` | -| [Project](https://docs.openstack.org/api-ref/identity/v3/index.html?expanded=list-users-detail#projects) | Run a Query on Openstack Projects | [PROJECTS.md](query_docs/PROJECTS.md) | `from openstack_query import ProjectQuery` | -| [Flavor](https://docs.openstack.org/api-ref/compute/#flavors) | Run a Query on Openstack Flavors | [FLAVORS.md](query_docs/FLAVORS.md) | `from openstack_query import FlavorQuery` | +| Openstack Resource | Description | Reference for Query Object | How to Import | +|----------------------------------------------------------------------------------------------------------|----------------------------------------|------------------------------------------|----------------------------------------------| +| [Servers](https://docs.openstack.org/api-ref/compute/#servers-servers) | Run a Query on Openstack Servers (VMs) | [SERVERS.md](query_docs/SERVERS.md) | `from openstackquery import ServerQuery` | +| [Users](https://docs.openstack.org/api-ref/identity/v3/index.html?expanded=list-users-detail#users) | Run a Query on Openstack Users | [USERS.md](query_docs/USERS.md) | `from openstackquery import UserQuery` | +| [Project](https://docs.openstack.org/api-ref/identity/v3/index.html?expanded=list-users-detail#projects) | Run a Query on Openstack Projects | [PROJECTS.md](query_docs/PROJECTS.md) | `from openstackquery import ProjectQuery` | +| [Flavor](https://docs.openstack.org/api-ref/compute/#flavors) | Run a Query on Openstack Flavors | [FLAVORS.md](query_docs/FLAVORS.md) | `from openstackquery import FlavorQuery` | +| [Hypervisor](https://docs.openstack.org/api-ref/compute/#hypervisors-os-hypervisors) | Run a Query on Openstack Hypervisors | [HYPERVISORS](query_docs/HYPERVISORS.md) | `from openstackquery import HypervisorQuery` | # ### select @@ -25,32 +26,21 @@ The query library currently supports queries on the following Openstack resource This is mutually exclusive to returning objects using `select_all()` which will return every available property -```python -def select(*props: Union[str, PropEnum]) -``` **Arguments**: -- `props`: one or more properties to collect described as enum or an equivalent string alias. - - e.g. If you're querying servers with `ServerQuery` - appropriate enum is `ServerProperties`, +- `props`: one or more properties to collect (strings). - see the specific query page e.g. [SERVERS.md](query_docs/SERVERS.md) on supported properties and string aliases for that query Running `select()` again will override all currently selected properties from previous `select()` call -`select()` and `select_all()` calls will be ignored when `to_objects()` is invoked +`select()` and `select_all()` calls will be ignored when invoking `to_objects()` `select()` is mutually exclusive to `select_all()` **Examples** ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties - -# create a ServerQuery and find server names and ids -query = ServerQuery() -query.select(ServerProperties.SERVER_NAME, ServerProperties.SERVER_ID) - -# or using the equivalent string aliases -query.select("server_name", "server_id") +from openstackquery import ServerQuery +ServerQuery().select("server_name", "server_id") ``` # @@ -59,14 +49,10 @@ query.select("server_name", "server_id") `select_all()` will set the query to output all properties stored for the property to be returned . Mutually exclusive to returning specific properties using select() -```python -def select_all() -``` **Arguments**: - None Running `select_all()` will override currently selected properties from previous `select()` calls - `select_all()` will not work if `to_objects` is called - since it returns Openstack objects # @@ -74,97 +60,81 @@ Running `select_all()` will override currently selected properties from previous `where()` allows you to specify conditions for the query. `where()` requires a preset-property pair to work. -- A preset is a special enum that defines the logic to query by - see [PRESETS.md](PRESETS.md) +- A preset is a special string that defines the logic to query by - see [PRESETS.md](PRESETS.md) - A property is what the preset will be used on -- (optional) A set of key-word arguments that the preset-property pair require - like a value to compare against - -This can be called multiple times to define multiple conditions for the query - acts as Logical AND. +- (optional) A set of key-word arguments that the preset-property pair require - like a value(s) to compare against -```python -def where(preset: Union[str, QueryPresets], prop: Union[str, PropEnum], **kwargs) -``` +This can be called multiple times to define multiple conditions for the query - acts as Logical `AND`. **Arguments**: -- `preset`: QueryPreset Enum (or equivalent string alias) to use +- `preset`: QueryPreset string to use - this specifies the logic to refine the query by. See [PRESETS.md](../PRESETS.md). -- `prop`: Property Enum (or equivalent string alias) that the query preset will be used on - - - e.g. If you're querying servers with `ServerQuery` - appropriate enum is `ServerProperties` - - some presets can only accept certain props - see [FILTER_MAPPINGS.md](../FILTER_MAPPINGS.md) +- `prop`: Property string alias that the query preset will be used on - + - some presets can only accept certain properties - see [FILTER_MAPPINGS.md](../FILTER_MAPPINGS.md) - `kwargs`: a set of optional arguments to pass along with the query preset - these kwargs are dependent on the preset - see [PRESETS.md](../PRESETS.md) **Example(s)** To query for servers which are in "error" state - the values would be: -- preset - `QueryPresetsGeneric.EQUAL_TO` -- prop - `ServerProperties.SERVER_STATUS` +- preset - `"equal_to"` +- prop - `"status"` - value(s) - `value="ERROR"` the `where` call would be like so: ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() query.select_all() -# setup filter server_status = ERROR +# setup filter status = ERROR query.where( - preset=QueryPresetsGeneric.EQUAL_TO, - prop=ServerProperties.SERVER_STATUS, + preset="equal_to", + prop="status", value="ERROR" ) - -# or using the equivalent string aliases -query.where("EQUAL_TO", "server_status", value="ERROR") ``` # ### sort\_by `sort_by` allows you to sort results by given property(ies) before outputting. - It allows sorting by multiple keys if you provide multiple `sort_by` tuples. -```python -def sort_by(*sort_by: Tuple[Union[str, PropEnum], Union[str, SortOrder]]) -``` - **Arguments**: - `sort_by`: Takes any number of tuples - the tuples must consist of two values: - - a property enum (or equivalent alias) to sort by - - e.g. If you're querying servers with `ServerQuery` - appropriate enum is `ServerProperties` - - an enum (or equivalent alias) representing the sort order - - `SortOrder.ASC` (for ascending) or `SortOrder.DESC` (for descending) + - a property (string) to sort by + - a string representing the sort order + - `"ascending"` for ascending + - `"descending"` for descending -| SortOrder Enum | Description | Alias(es) (case-insensitive) | -|----------------|--------------------------|------------------------------| -| SortOrder.ASC | sort in ascending order | "ascending", "asc" | -| SortOrder.DESC | sort in descending order | "descending", "desc" | +| SortOrder String | Description | +|--------------------------|--------------------------| +| `"ascending"`, `"asc"` | sort in ascending order | +| `"descending"`, `"desc"` | sort in descending order | **Note**: You can sort by properties you haven't 'selected' for using `select()` **Examples** ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric -from enum.query.sort_order import SortOrder +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) +query.select("id", "name") + +# run the query query.run("openstack-domain", as_admin=True, all_projects=True) # sort by name in descending, then sort by id in ascending query.sort_by( - (ServerProperties.SERVER_ID, SortOrder.DESC), - (ServerProperties.SERVER_NAME, SortOrder.ASC) + ("id", "descending"), + ("name", "ascending") ) # or using equivalent string aliases @@ -199,18 +169,12 @@ we sort by server_id in ascending order etc. - unique values found for a property specified in `group_by` - a set of pre-defined groups which define how to group results based on their value of the property specified in `group_by` -```python -def group_by(group_by: Union[str, PropEnum], - group_ranges: Optional[Dict[str, List[PropValue]]] = None, - include_ungrouped_results: bool = False) -``` Public method used to configure how to group results. **Arguments**: -- `group_by`: a property enum (or equivalent string alias) representing the property you want to group by - - e.g. If you're querying servers with `ServerQuery` - appropriate enum is `ServerProperties` +- `group_by`: a property (string) representing the property you want to group by - `group_ranges`: (optional) a dictionary of group mappings - the keys are unique group names - the values are a list of values that `group_by` property could have to be included in that group @@ -225,17 +189,15 @@ Running an `ANY_IN` command and grouping results ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) +query.select("id", "name") # setup filter server_status = ERROR query.where( - preset="ANY_IN" + preset="ANY_IN", prop="server_status", values=["ERROR", "SHUTOFF"] ) @@ -263,16 +225,11 @@ x = query.to_objects() `run()` will run the query. `run()` will apply all predefined conditioned set by `where` calls -```python -def run(cloud_account: Union[str, CloudDomains], - from_subset: Optional[List[OpenstackResourceObj]] = None, - **kwargs) -``` **Arguments**: -- `cloud_account`: A String or a CloudDomains Enum representing the clouds configuration to use - - this should be the domain set in the `clouds.yaml` file located in `.config/openstack/clouds.yaml` +- `cloud_account`: A string representing the clouds configuration to use + - this should be the domain set in the `clouds.yaml` file located in `.config/openstack/clouds.yaml` (or `/etc/openstack/clouds.yaml`) - `from_subset`: (optional) a subset of openstack resources to run query on instead of querying for them using openstacksdk - **NOTE:** this is going to be deprecated soon - look at using `then()` or `append_from()` for a better way to @@ -289,11 +246,6 @@ def run(cloud_account: Union[str, CloudDomains], Like all output methods - it will parse the results set in `sort_by()`, `group_by()` and requires `run()` to have been called first - this method will not run `select` - instead outputting raw results (openstack resource objects) -```python -def to_objects( - groups: Optional[List[str]] = None) -> Union[Dict[str, List], List] -``` - This is either returned as a list if `to_groups` has not been set, or as a dict if `to_groups` was set **Arguments**: @@ -304,9 +256,7 @@ This is either returned as a list if `to_groups` has not been set, or as a dict ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() @@ -336,11 +286,6 @@ Like all output methods - it will parse the results set in `sort_by()`, `group_b - If this query is chained from previous query(ies) by `then()` - the previous results will also be included - If any `append_from` calls have been run - the properties appended will also be included -```python -def to_props( - flatten: bool = False, - groups: Optional[List[str]] = None) -> Union[Dict[str, List], List] -``` This is either returned as a list if `to_groups` has not been set, or as a dict if `to_groups` was set **Arguments**: @@ -413,18 +358,16 @@ print(grouped_query.to_props(flatten=True)) ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) +query.select("id", "name") query.run("openstack-domain", as_admin=True, all_projects=True) # setup filter server_status = ERROR query.where( - preset=QueryPresetsGeneric.EQUAL_TO, - prop=ServerProperties.SERVER_STATUS, + preset="equal_to", + prop="status", value="ERROR" ) @@ -453,12 +396,6 @@ Like all output methods - it will parse the results set in `sort_by()`, `group_b - If this query is chained from previous query(ies) by `then()` - the previous results will also be included - If any `append_from` calls have been run - the properties appended will also be included -```python -def to_string(title: Optional[str] = None, - groups: Optional[List[str]] = None, - **kwargs) -> str -``` - **Arguments**: - `title`: An optional title to print on top @@ -472,18 +409,16 @@ def to_string(title: Optional[str] = None, ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) +query.select("id", "name") # setup filter server_status = ERROR query.where( - preset=QueryPresetsGeneric.EQUAL_TO, - prop=ServerProperties.SERVER_STATUS, + preset="equal_to", + prop="status", value="ERROR" ) query.run("openstack-domain", as_admin=True, all_projects=True) @@ -510,11 +445,6 @@ Like all output methods - it will parse the results set in `sort_by()`, `group_b - If this query is chained from previous query(ies) by `then()` - the previous results will also be included - If any `append_from` calls have been run - the properties appended will also be included -```python -def to_html(title: Optional[str] = None, - groups: Optional[List[str]] = None, - **kwargs) -> str -``` **Arguments**: @@ -530,18 +460,16 @@ def to_html(title: Optional[str] = None, ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enum.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # create a ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) +query.select("id", "name") # setup filter server_status = ERROR query.where( - preset=QueryPresetsGeneric.EQUAL_TO, - prop=ServerProperties.SERVER_STATUS, + preset="equal_to", + prop="status", value="ERROR" ) query.run("openstack-domain", as_admin=True, all_projects=True) @@ -561,7 +489,7 @@ print(query.to_html()) ``` # -### to_csv (Under development) +### to_csv `to_csv` is an output method that will write the output into csv file(s). If the results are grouped, each group will be written to a file under `.csv` Like all output methods - it will parse the results set in `sort_by()`, `group_by()` and requires `run()` to have been called first @@ -569,10 +497,6 @@ Like all output methods - it will parse the results set in `sort_by()`, `group_b - If this query is chained from previous query(ies) by `then()` - the previous results will also be included - If any `append_from` calls have been run - the properties appended will also be included -```python -def to_csv(dirpath: str) -``` - **Arguments**: **NOTE:** More args for to_csv method under development @@ -598,15 +522,10 @@ This can only work if the current query and the next query have a shared common **NOTE:** You will NOT be able to group/sort by forwarded properties in the new query -```python -def then(query_type: Union[str, QueryTypes], - keep_previous_results: bool = True) -``` - **Arguments**: -- `query_type`: an enum (or equivalent string alias) representing the new query to chain into - - see specific documentation for resource for valid ways `query_types` +- `query_type`: a string representing the new query to chain into + - see specific documentation for `query_types` under `docs/user_docs/query_docs` - `keep_previous_results`: flag that: - If True - will forward outputs from this query (and previous chained queries) onto new query. @@ -623,26 +542,21 @@ This method will run a secondary query on top of this one to get required proper - Query must be run first by calling `run()` before calling `append_from()` - A shared common property must exist between this query and the new query - - i.e. both ServerQuery and UserQuery share the 'USER_ID' property so `append_from` is possible between them + - i.e. both ServerQuery and UserQuery share the `'USER_ID'` property so `append_from` is possible between them - see specific documentation for resource for valid ways to chain **NOTE:** You will NOT be able to group/sort by forwarded properties in the new query -```python -def append_from(query_type: Union[str, QueryTypes], - cloud_account: Union[str, CloudDomains], *props: Union[str, PropEnum]) -``` **Arguments**: -- `query_type`: an enum (or equivalent string alias) representing the new query to chain into +- `query_type`: a string representing the new query to chain into - see specific documentation for resource for valid ways `query_types` -- `cloud_account`: A CloudDomains Enum (or equivalent string alias) for the clouds configuration to use - - this should be the domain set in the `clouds.yaml` file located in `.config/openstack/clouds.yaml` -- `props`: one or more properties to collect described as enum (or equivalent string alias) from new query. - - e.g. If you're appending server properties (i.e. `append_from("ServerQuery" ...)`) the appropriate enum is `ServerProperties` - - see specific documentation for resource you want to append props from to see valid props +- `cloud_account`: A string for the clouds configuration to use + - this should be the domain set in the `clouds.yaml` file located in `.config/openstack/clouds.yaml` (or `/etc/openstack/clouds.yaml`) +- `props`: a list of strings representing the properties to collect from new query. + - see specific documentation for resource you want to append props `docs/user_docs/query_docs` **Examples:** diff --git a/docs/user_docs/PRESETS.md b/docs/user_docs/PRESETS.md index e381dab..261793e 100644 --- a/docs/user_docs/PRESETS.md +++ b/docs/user_docs/PRESETS.md @@ -7,73 +7,53 @@ This allows the query to be defined by multiple presets and makes it clear what **Example:** To find all servers in a list of projects which are shutoff or errored - the queries can be: ```python -q1 = ServerQuery().where(preset=ANY_IN, prop=project_id, values=["project1", "project2"]) -q2 = q1.where(preset=ANY_IN, prop=server_status, values=["ERROR", "SHUTOFF"]) -``` - -Presets are stored as enums. There are currently the following enum classes: - -| Preset Class | Description | -|-----------------------------------------------|-------------------------------------------------------------------------------| -| [QueryPresetsGeneric](#QueryPresetsGeneric) | Used to hold presets that can be applied to any property (no matter the type) | -| [QueryPresetsString](#QueryPresetsString) | Used to hold presets that can only be applied to string-type properties | -| [QueryPresetsInteger](#QueryPresetsInteger) | Used to hold presets that can only be applied to integer-type properties | -| [QueryPresetsDateTime](#QueryPresetsDateTime) | Used to hold presets that can only be appli | - +from openstackquery import ServerQuery -## Importing presets - -Presets can be imported like so: -```python -from enums.query.query_presets import QueryPresetsGeneric, QueryPresetsString, QueryPresetsInteger, QueryPresetsDateTime +q1 = ServerQuery().where(preset="ANY_IN", prop="project_id", values=["project1", "project2"]) +q2 = q1.where(preset="ANY_IN", prop="status", values=["ERROR", "SHUTOFF"]) ``` -**NOTE: WIP - Not implemented yet** - -Alternatively, you can also pass string aliases instead of a preset Enum (see reference below). -(These are case-insensitive) - # Reference ## QueryPresetsGeneric QueryPresetsGeneric has the following presets: -| Preset | Aliases | Description | Extra Parameters | -|--------------|-------------------|--------------------------------------------------------------------------------------|---------------------------------------------------------------| -| ANY_IN | "in" | Finds objects which have a property matching any of a given set of values | `values: List` - a list of property values to compare against | -| NOT_ANY_IN | "not in" | Finds objects which have a property that does not match any of a given set of values | `values: List` - a list of property values to compare against | -| EQUAL_TO | "equal", "==" | Finds objects which have a property matching a given value | `value` - a single value to compare against | -| NOT_EQUAL_TO | "not equal", "!=" | Finds objects which have a property that does not match a given value | `value` - a single value to compare against | +| Aliases | Description | Extra Parameters | +|----------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------------------------| +| `any_in`, `in` | Finds objects which have a property matching any of a given set of values | `values: List` - a list of property values to compare against | +| `not_any_in`, `not_in` | Finds objects which have a property that does not match any of a given set of values | `values: List` - a list of property values to compare against | +| `equal_to`, `equal`, `==` | Finds objects which have a property matching a given value | `value` - a single value to compare against | +| `not_equal_to` `not_equal`, `!=` | Finds objects which have a property that does not match a given value | `value` - a single value to compare against | ## QueryPresetsString QueryPresetsString has the following presets: -| Preset | Aliases | Description | Extra Parameters | -|---------------|------------------------|------------------------------------------------------------------|---------------------------------------------------------------------| -| MATCHES_REGEX | "regex", "match_regex" | Finds objects which have a property that matches a regex pattern | `value: str` - a string which can be converted into a regex pattern | +| Aliases | Description | Extra Parameters | +|-----------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------------| +| `matches_regex`, `regex`, `match_regex` | Finds objects which have a property that matches a regex pattern | `value: str` - a string which can be converted into a regex pattern | ## QueryPresetsInteger QueryPresetsInteger has the following presets: -| Preset | Aliases | Description | Extra Parameters | -|--------------------------|---------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| -| GREATER_THAN | `None` | Finds objects which have an integer/float property greater than a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | -| LESS_THAN | `None` | Finds objects which have an integer/float property less than a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | -| GREATER_THAN_OR_EQUAL_TO | `None` | Finds objects which have an integer/float property greater than or equal to a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | -| LESS_THAN_OR_EQUAL_TO | `None` | Finds objects which have an integer/float property less than or equal to a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | +| Aliases | Description | Extra Parameters | +|----------------------------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| +| `greater_than`, `>` | Finds objects which have an integer/float property greater than a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | +| `less_than`, `<` | Finds objects which have an integer/float property less than a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | +| `greater_than_or_equal_to`, `>=` | Finds objects which have an integer/float property greater than or equal to a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | +| `less_than_or_equal_to`, `<=` | Finds objects which have an integer/float property less than or equal to a threshold | `value: Union[int, float]` - an integer or float threshold to compare against | ## QueryPresetsDateTime QueryPresetsDateTime has the following presets: -| Preset | Aliases | Description | Extra Parameters | -|--------------------------|---------|--------------------------------------------------------------------------------------------------------|------------------| -| OLDER_THAN | `None` | Finds objects which have an datetime property older than a given relative time threshold | see below | -| YOUNGER_THAN | `None` | Finds objects which have an datetime property younger than a given relative time threshold | see below | -| OLDER_THAN_OR_EQUAL_TO | `None` | Finds objects which have an datetime property older than or equal to a given relative time threshold | see below | -| YOUNGER_THAN_OR_EQUAL_TO | `None` | Finds objects which have an datetime property younger than or equal to a given relative time threshold | see below | +| Aliases | Description | Extra Parameters | +|----------------------------------|--------------------------------------------------------------------------------------------------------|------------------| +| `older_than`, `>` | Finds objects which have an datetime property older than a given relative time threshold | see below | +| `younger_than`, `<` | Finds objects which have an datetime property younger than a given relative time threshold | see below | +| `older_than_or_equal_to`, `>=` | Finds objects which have an datetime property older than or equal to a given relative time threshold | see below | +| `younger_than_or_equal_to`, `<=` | Finds objects which have an datetime property younger than or equal to a given relative time threshold | see below | ### Extra Parameters - `days: int` - (Optional) relative number of days since current time to compare against diff --git a/docs/user_docs/USAGE.md b/docs/user_docs/USAGE.md index dd516b5..cd17160 100644 --- a/docs/user_docs/USAGE.md +++ b/docs/user_docs/USAGE.md @@ -5,18 +5,16 @@ The following document contains different ways to use the query library Find Errored and Shutoff VMs ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enums.query.query_presets import QueryPresetsGeneric +from openstackquery import ServerQuery # Create a Query Object that will search for Openstack VMs query = ServerQuery() # Select - when outputting - only output the selected properties from each VM -query.select(ServerProperties.SERVER_NAME, ServerProperties.SERVER_ID) +query.select("name", "id") -# Where - define a preset (ANY_IN), a property to apply it to (server_status) and value/s to look for (ERROR, SHUTOFF) -query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) +# Where - define a preset ("any in" = match any value given), a property to apply it to (server status) and value/s to look for (ERROR, SHUTOFF) +query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) # Run - this will run the query in the "prod" cloud domain and with meta-params as_admin and all_projects. # This will run the query as an admin and will find VMs on every available project @@ -24,7 +22,7 @@ query.run("prod", as_admin=True, all_projects=True) # Group By - This will group the results by a property - project_id # NOTE: group by property and selected property are completely independent -query.group_by(ServerProperties.PROJECT_ID) +query.group_by("project_id") # Output the query results to table(s) (stored as a string) print(query.to_string()) @@ -37,22 +35,20 @@ Find Errored and Shutoff VMs - AND haven't been updated in 60 days ```python -from openstack_query import ServerQuery -from enums.query.props.server_properties import ServerProperties -from enums.query.query_presets import QueryPresetsGeneric, QueryPresetsDateTime +from openstackquery import ServerQuery query = ServerQuery() -query.select(ServerProperties.SERVER_NAME, ServerProperties.SERVER_ID) -query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) +query.select("name", "id") +query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) # ADDITIONAL WHERE - ACTS AS LOGICAL AND # Extra query preset refines search to look for errored and shutoff VMs that haven't been updated in 60 days -query.where(QueryPresetsDateTime.OLDER_THAN, ServerProperties.SERVER_LAST_UPDATED_DATE, days=60) +query.where("older_than", "last_updated_date", days=60) query.run("prod", as_admin=True, all_projects=True) -query.group_by(ServerProperties.PROJECT_ID) +query.group_by("id") print(query.to_string()) ``` @@ -64,36 +60,32 @@ Find Errored and Shutoff VMs ```python -from openstack_query import UserQuery -from enums.query.props.server_properties import ServerProperties -from enums.query.props.user_properties import UserProperties -from enums.query.query_presets import QueryPresetsGeneric, QueryPresetsDateTime - +from openstackquery import UserQuery # setup and run a User Query to get user info for all users in a specific domain user_query = UserQuery() -user_query.select(UserProperties.USER_NAME, UserProperties.USER_EMAIL) -user_query.where(QueryPresetsGeneric.EQUAL_TO, UserProperties.USER_DOMAIN_ID, value="user-domain-id1") +user_query.select("name", "email") +user_query.where("equal_to", "domain_id", value="stfc") user_query.run("prod") # We're going to create a Server Query using the results from the first query # This is the same as doing: -# user_ids = user_query.group_by(UserProperties.USER_ID).to_props().keys() -# ServerQuery().where(QueryPresetsGeneric.ANY_IN, ServerProperties.USER_ID, values=list(user_ids)) +# user_ids = user_query.group_by("id").to_props().keys() +# ServerQuery().where("any_in", "user_id", values=list(user_ids)) # NOTE: setting keep_previous_results=True will carry over properties we've selected for from the previous query server_query = user_query.then("SERVER_QUERY", keep_previous_results=True) # Then we continue as normal! -server_query.select(ServerProperties.SERVER_NAME, ServerProperties.SERVER_ID) -server_query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) -server_query.where(QueryPresetsDateTime.OLDER_THAN, ServerProperties.SERVER_LAST_UPDATED_DATE, days=60) +server_query.select("name", "id") +server_query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) +server_query.where("older_than", "last_updated_date", days=60) server_query.run("prod", as_admin=True, all_projects=True) -server_query.group_by(ServerProperties.PROJECT_ID) +server_query.group_by("project_id") # These results will contain VM associated values for user_name and user_email -# results will only contain VMs belonging to users in "user-domain-id1" +# results will only contain VMs belonging to users in "stfc" print(server_query.to_string()) ``` @@ -105,65 +97,61 @@ Find Errored and Shutoff VMs - AND include the PROJECT_NAME ```python -from openstack_query import UserQuery -from enums.query.props.server_properties import ServerProperties -from enums.query.props.user_properties import UserProperties -from enums.query.props.project_properties import ProjectProperties -from enums.query.query_presets import QueryPresetsGeneric, QueryPresetsDateTime - +from openstackquery import UserQuery # setup and run a User Query to get user info for all users in a specific domain user_query = UserQuery() -user_query.select(UserProperties.USER_NAME, UserProperties.USER_EMAIL) -user_query.where(QueryPresetsGeneric.EQUAL_TO, UserProperties.USER_DOMAIN_ID, value="user-domain-id1") +user_query.select("name", "email") +user_query.where("equal_to", "domain_id", value="stfc") user_query.run("prod") server_query = user_query.then("SERVER_QUERY", keep_previous_results=True) -server_query.select(ServerProperties.SERVER_NAME, ServerProperties.SERVER_ID) -server_query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) -server_query.where(QueryPresetsDateTime.OLDER_THAN, ServerProperties.SERVER_LAST_UPDATED_DATE, days=60) +server_query.select("name", "id") +server_query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) +server_query.where("older_than", "last_updated_date", days=60) server_query.run("prod", as_admin=True, all_projects=True) # We need to get project name by running append_from() # append_from() command below is the same as doing the following: -# project_ids = server_query.group_by(ServerProperties.PROJECT_ID).to_props().keys() -# p = ProjectQuery().select(ProjectProperties.PROJECT_NAME).where( -# QueryPresetsGeneric.ANY_IN, ProjectProperties.PROJECT_ID, values=list(project_ids) +# project_ids = server_query.group_by("project_id").to_props().keys() +# p = ProjectQuery().select("name").where( +# "any_in", "id", values=list(project_ids) # ) # p.run("prod") # res = p.to_props() # `res` is then combined zipped together into the current output -server_query.append_from("PROJECT_QUERY", "prod", [ProjectProperties.PROJECT_ID]) +server_query.append_from("PROJECT_QUERY", "prod", ["project_id"]) # Note it's not possible to group by external properties (yet) -server_query.group_by(ServerProperties.PROJECT_ID) +server_query.group_by("project_id") # This will print out results and includes project name for every VM too server_query.to_string() ``` -### NOTE - requirement to use enums for properties and query presets will be removed soon - see issue [88](https://github.com/stfc/st2-cloud-pack/issues/88) # Grouping Usage ## Group By Unique Values By default - the unique values of a given property found in results as the 'group_key' ```python +from openstackquery import ServerQuery -query = ServerQuery().select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) -query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) +query = ServerQuery().select("id", "name") +query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) query.run("prod") # groups by unique values of server_status found in results # - in this case we'll get 2 groups - 'ERROR' and 'SHUTOFF' are the group keys -query.group_by(ServerProperties.SERVER_STATUS) +query.group_by("status") ``` ## Group By Given Group Keys You can specify you're own group_keys by setting the values that belong to each group like so: ```python +from openstackquery import ServerQuery -query = ServerQuery().select(ServerProperties.SERVER_ID, ServerProperties.SERVER_NAME) -query.where(QueryPresetsGeneric.ANY_IN, ServerProperties.SERVER_STATUS, values=["ERROR", "SHUTOFF"]) +query = ServerQuery().select("id", "name") +query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) query.run("prod") # groups by pre-configured groups @@ -178,34 +166,14 @@ group_keys = { # - group1 will contain VMs belonging to project with ids project-id1 and project-id2 # - group2 will contain VMs belonging to project with ids project-id3 and project-id4 # - all other VMs will be ignored -query.group_by(ServerProperties.PROJECT_ID, group_keys=group_keys) +query.group_by("project_id", group_keys=group_keys) ``` ### Note About Aliases -All these examples use Enums as inputs to various API methods. - -Any API methods that take Enums as input can also accept strings that are known as string aliases. -These aliases will be converted to a specific Enum implicitly. - -The point of aliases is to be intuitive, and won't require you to learn the specific syntax of the query library. -To see which aliases are available: +The strings used for presets, properties, and query types 1. For Preset aliases for use with `where()` see [Presets.md](PRESETS.md) 2. For Property aliases for use with `select()`, `where()` and others, see the specific page in [query_docs](query_docs) 3. For Query aliases for use with `then()`, append_from()`, see the specific page in [query_docs](query_docs) 4. For other aliases, see API method reference in [API.md](API.md) - -**NOTE**: passing a string alias that exactly matches the enum will always be accepted. E.g: - -```python -query.select(ServerProperties.SERVER_ID) - -# is equivalent to -query.select("server_id") - -# both are equivalent to using aliases like: -query.select("id") -# or -query.select("uuid") -``` diff --git a/docs/user_docs/query_docs/FLAVORS.md b/docs/user_docs/query_docs/FLAVORS.md index 1546a98..c837812 100644 --- a/docs/user_docs/query_docs/FLAVORS.md +++ b/docs/user_docs/query_docs/FLAVORS.md @@ -9,36 +9,29 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/compute/#flavors) for mo To Query for Flavors using the Query Library, you can import `FlavorQuery()` like so: ```python -from openstack_query import FlavorQuery +from openstackquery import FlavorQuery ``` `FlavorQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `FlavorQuery` is `FlavorProperties`. You can import `FlavorProperties` like so: - -```python -from enums.query.props.flavor_properties import FlavorProperties -``` - -`FlavorProperties` exposes the following properties: - -| Property Enum | Type | Aliases (case-insensitive) | Description | -|--------------------|----------|------------------------------------------------------|-------------------------------------------------------------------------------------------------| -| FLAVOR_DESCRIPTION | `string` | "description", "desc" | The description of the flavor | -| FLAVOR_DISK | `int` | "disk", "disk_size" | Size of the disk this flavor offers. Type: int | -| FLAVOR_EPHEMERAL | `int` | "ephemeral", "ephemeral_disk", "ephemeral_disk_size" | Size of the ephemeral data disk attached to this server. Type: int | -| FLAVOR_ID | `string` | "id", "uuid" | Unique ID Openstack has assigned the flavor. | -| FLAVOR_IS_DISABLED | `bool` | "is_disabled" | Indicates whether flavor is disabled.
True if disabled, False if not | -| FLAVOR_IS_PUBLIC | `bool` | "is_public" | Indicates if flavor is available to all projects.
True if publicly available, False if not | -| FLAVOR_NAME | `string` | "name" | Name of the flavor | -| FLAVOR_RAM | `int` | "ram", "ram_size | The amount of RAM (in MB) this flavor offers. Type: int | -| FLAVOR_SWAP | `int` | "swap", "swap_size" | Size of the swap partitions. | -| FLAVOR_VCPU | `int` | "vcpu", "vcpus" | The number of virtual CPUs this flavor offers. Type: int | +Each `Flavor` has the following properties + +| Return Type | Property Name(s) (case-insensitive) | Description | +|-------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------| +| `string` | "description", "desc" | The description of the flavor | +| `int` | "disk", "disk_size" | Size of the disk this flavor offers. Type: int | +| `int` | "ephemeral", "ephemeral_disk", "ephemeral_disk_size" | Size of the ephemeral data disk attached to this server. Type: int | +| `string` | "id", "uuid" | Unique ID Openstack has assigned the flavor. | +| `bool` | "is_disabled" | Indicates whether flavor is disabled.
True if disabled, False if not | +| `bool` | "is_public" | Indicates if flavor is available to all projects.
True if publicly available, False if not | +| `string` | "name" | Name of the flavor | +| `int` | "ram", "ram_size | The amount of RAM (in MB) this flavor offers. Type: int | +| `int` | "swap", "swap_size" | Size of the swap partitions. | +| `int` | "vcpu", "vcpus" | The number of virtual CPUs this flavor offers. Type: int | Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc -Alternatively, you can pass property aliases (passed as string) instead (currently WIP) ## Chaining This section details valid mappings you can use to chain onto other queries or from other queries to chain into a `FlavorQuery` object. @@ -47,9 +40,9 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|-------------------------|---------------------------| -| QueryTypes.FLAVOR_QUERY | "flavor", "flavors" | +| Aliases (case-insensitive) | +|----------------------------------------------------| +| "flavor", "flavors", "flavor_query", "flavorquery" | @@ -57,17 +50,17 @@ The aliases that can be used for the query when chaining are listed below: A `FlavorQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | Documentation | -|----------------------------|----------------------------|-------------|--------------------------------|--------------------------| -| FlavorProperties.FlAVOR_ID | ServerProperties.FLAVOR_ID | One-to-Many | `FlavorQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | +| Prop 1 | Prop 2 | Type | Maps | Documentation | +|--------|---------------|-------------|--------------------------------|--------------------------| +| `"id"` | `"flavor_id"` | One-to-Many | `FlavorQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | ## Chaining to -Chaining from other `FlavorQuery` requires passing `FLAVOR_QUERY` or any aliases mentioned above as the `query_type` +Chaining from other `FlavorQuery` requires passing `flavor_query` or any aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|---------------|----------------------------|----------------------------|-------------|--------------------------| -| `ServerQuery` | ServerProperties.FLAVOR_ID | FlavorProperties.FLAVOR_ID | Many-to-One | [SERVERS.md](SERVERS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|---------------|---------------|--------|-------------|--------------------------| +| `ServerQuery` | `"flavor_id"` | `"id"` | Many-to-One | [SERVERS.md](SERVERS.md) | ## run() meta-parameters diff --git a/docs/user_docs/query_docs/HYPERVISORS.md b/docs/user_docs/query_docs/HYPERVISORS.md index f04ee7d..7856166 100644 --- a/docs/user_docs/query_docs/HYPERVISORS.md +++ b/docs/user_docs/query_docs/HYPERVISORS.md @@ -10,41 +10,34 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/compute/#hypervisors-os- To Query for Hypervisors using the Query Library, you can import `HypervisorQuery()` like so: ```python -from openstack_query import HypervisorQuery +from openstackquery import HypervisorQuery ``` `HypervisorQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `HypervisorQuery` is `HypervisorProperties`. You can import `HypervisorProperties` like so: - -```python -from enums.query.props.hypervisor_properties import HypervisorProperties -``` - -`HypervisorProperties` exposes the following properties: - -| Property Enum | Type | Aliases (case-insensitive) | Description | -|-------------------------------|----------|------------------------------------|-----------------------------------------------------------------| -| HYPERVISOR_CURRENT_WORKLOAD | `int` | "current_workload", "workload" | The number of tasks the hypervisor is responsible for | -| HYPERVISOR_DISK_FREE | `int` | "local_disk_free", "free_disk_gb" | The local disk space remaining on this hypervisor(in GiB) | -| HYPERVISOR_DISK_SIZE | `int` | "local_disk_size", "local_gb" | Total local disk size on this hypervisor (in GiB). | -| HYPERVISOR_DISK_USED | `int` | "local_disk_used", "local_gb_used" | The local disk space allocated on this hypervisor(in GiB) | -| HYPERVISOR_ID | `string` | "id", "uuid", "host_id" | ID of the Hypervisor | -| HYPERVISOR_IP | `string` | "ip", "host_ip" | The IP address of the hypervisor’s host | -| HYPERVISOR_MEMORY_FREE | `int` | "memory_free", "free_ram_mb" | The free RAM on this hypervisor(in MiB). | -| HYPERVISOR_MEMORY_SIZE | `int` | "memory_size", "memory_mb" | Total RAM size for this hypervisor(in MiB). | -| HYPERVISOR_MEMORY_USED | `int` | "memory_used", "memory_mb_used" | RAM currently being used on this hypervisor(in MiB). | -| HYPERVISOR_NAME | `string` | "name", "host_name" | Hypervisor Hostname | -| HYPERVISOR_SERVER_COUNT | `int` | "running_vms" | The number of running VMs on this hypervisor. | -| HYPERVISOR_STATE | `string` | "state" | The state of the hypervisor. One of up or down. | -| HYPERVISOR_STATUS | `string` | "status" | The status of the hypervisor. One of enabled or disabled. | -| HYPERVISOR_VCPUS | `int` | "vcpus" | The number of vCPUs on this hypervisor. | -| HYPERVISOR_VCPUS_USED | `int` | "vcpus_used" | The number of vCPUs currently being used on this hypervisor. | -| HYPERVISOR_DISABLED_REASON | `string` | "disabled_reason" | Comment of why the hypervisor is disabled, None if not disabled | -| HYPERVISOR_UPTIME_DAYS | `int` | "uptime" | The number of days the hypervisor has been up | - +`Hypervisors` have the following properties: + +| Return Type | Property Name(s) (case-insensitive) | Description | +|-------------|-------------------------------------|-----------------------------------------------------------------| +| `int` | "current_workload", "workload" | The number of tasks the hypervisor is responsible for | +| `int` | "local_disk_free", "free_disk_gb" | The local disk space remaining on this hypervisor(in GiB) | +| `int` | "local_disk_size", "local_gb" | Total local disk size on this hypervisor (in GiB). | +| `int` | "local_disk_used", "local_gb_used" | The local disk space allocated on this hypervisor(in GiB) | +| `string` | "id", "uuid", "host_id" | ID of the Hypervisor | +| `string` | "ip", "host_ip" | The IP address of the hypervisor’s host | +| `int` | "memory_free", "free_ram_mb" | The free RAM on this hypervisor(in MiB). | +| `int` | "memory_size", "memory_mb" | Total RAM size for this hypervisor(in MiB). | +| `int` | "memory_used", "memory_mb_used" | RAM currently being used on this hypervisor(in MiB). | +| `string` | "name", "host_name" | Hypervisor Hostname | +| `int` | "running_vms" | The number of running VMs on this hypervisor. | +| `string` | "state" | The state of the hypervisor. One of up or down. | +| `string` | "status" | The status of the hypervisor. One of enabled or disabled. | +| `int` | "vcpus" | The number of vCPUs on this hypervisor. | +| `int` | "vcpus_used" | The number of vCPUs currently being used on this hypervisor. | +| `string` | "disabled_reason" | Comment of why the hypervisor is disabled, None if not disabled | +| `string` | "uptime" | The total uptime of the hypervisor and info about average load | Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc @@ -55,9 +48,9 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|----------------------------|------------------------------| -| QueryTypes.HypervisorQuery | "hypervisor", "hypervisors" | +| Aliases (case-insensitive | +|--------------------------------------------------------------------| +| "hypervisor", "hypervisors", "hypervisor_query", "hypervisorquery" | @@ -65,17 +58,17 @@ The aliases that can be used for the query when chaining are listed below: A `HypervisorQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | Documentation | -|------------------------------------|---------------------------------|-------------|-------------------------------------|--------------------------| -| HypervisorProperties.HYPERVISOR_ID | ServerProperties.HYPERVISOR_ID | One-to-Many | `HypervisorQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | +| Prop 1 | Prop 2 | Type | Maps | Documentation | +|--------|-------------------|-------------|-------------------------------------|--------------------------| +| "name" | "hypervisor_name" | One-to-Many | `HypervisorQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | ## Chaining to -Chaining from other `HypervisorQuery` requires passing `HYPERVISOR_QUERY` or any aliases mentioned above as the `query_type` +Chaining from other `HypervisorQuery` requires passing `hypervisor_query` or any aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|---------------|--------------------------------|------------------------------------|-------------|--------------------------| -| `ServerQuery` | ServerProperties.HYPERVISOR_ID | HypervisorProperties.HYPERVISOR_ID | Many-to-One | [SERVERS.md](SERVERS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|---------------|-------------------|--------|-------------|--------------------------| +| `ServerQuery` | "hypervisor_name" | "name" | Many-to-One | [SERVERS.md](SERVERS.md) | ## run() meta-parameters diff --git a/docs/user_docs/query_docs/IMAGES.md b/docs/user_docs/query_docs/IMAGES.md index 42b8406..7efa39d 100644 --- a/docs/user_docs/query_docs/IMAGES.md +++ b/docs/user_docs/query_docs/IMAGES.md @@ -11,35 +11,29 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/image/v2/index.html) for To Query for Images using the Query Library, you can import `ImageQuery()` like so: ```python -from openstack_query import ImageQuery +from openstackquery import ImageQuery ``` `ImageQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `ImageQuery` is `ImageProperties`. You can import `ImageProperties` like so: - -```python -from enums.query.props.image_properties import ImageProperties -``` - -`ImageProperties` exposes the following properties: - -| Property Enum | Type | Aliases (case-insensitive) | Description | -|-------------------------|--------------|----------------------------|---------------------------------------------------------------------| -| IMAGE_CREATION_DATE | `string` (x) | "created_at" | The timestamp when this image was created. | -| IMAGE_CREATION_PROGRESS | `int` | "progress" | Image creation percentage, 0 to 100. 100 once Image is created | -| IMAGE_ID | `string` | "id", "uuid" | ID of the image | -| IMAGE_LAST_UPDATED_DATE | `string` (x) | "updated_at" | The timestamp when this image was last updated | -| IMAGE_MINIMUM_DISK | `int` | "min_ram", "ram" | The minimum disk size in GB that is required to boot the image. | -| IMAGE_MINIMUM_RAM | `int` | "min_disk", "disk" | The minimum amount of RAM in MB that is required to boot the image. | -| IMAGE_NAME | `string` | "name" | Name of the Image | -| IMAGE_SIZE | `int` | "size" | The size of the image data, in bytes. | -| IMAGE_STATUS | `string` | "status" | Image status | - +An `Image` has the following properties: + +| Return Type | Property Name(s) (case-insensitive) | Description | +|--------------|-------------------------------------|---------------------------------------------------------------------| +| `string` (x) | "created_at" | The timestamp when this image was created. | +| `int` | "progress" | Image creation percentage, 0 to 100. 100 once Image is created | +| `string` | "id", "uuid" | ID of the image | +| `string` (x) | "updated_at" | The timestamp when this image was last updated | +| `int` | "min_ram", "ram" | The minimum disk size in GB that is required to boot the image. | +| `int` | "min_disk", "disk" | The minimum amount of RAM in MB that is required to boot the image. | +| `string` | "name" | Name of the Image | +| `int` | "size" | The size of the image data, in bytes. | +| `string` | "status" | Image status | + +(x) - These are UTC timestamps in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc -Alternatively, you can pass property aliases (passed as string) instead (currently WIP) ## Chaining This section details valid mappings you can use to chain onto other queries or from other queries to chain into a `ImageQuery` object. @@ -48,9 +42,9 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|------------------------|---------------------------| -| QueryTypes.IMAGE_QUERY | "image", "images" | +| Aliases (case-insensitive) | +|------------------------------------------------| +| "image", "images", "image_query", "imagequery" | @@ -58,17 +52,17 @@ The aliases that can be used for the query when chaining are listed below: A `ImageQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | Documentation | -|--------------------------|---------------------------|-------------|-------------------------------|--------------------------| -| ImageProperties.IMAGE_ID | ServerProperties.IMAGE_ID | One-to-Many | `ImageQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | +| Prop 1 | Prop 2 | Type | Maps | Documentation | +|--------|------------|-------------|-------------------------------|--------------------------| +| "id" | "image_id" | One-to-Many | `ImageQuery` to `ServerQuery` | [SERVERS.md](SERVERS.md) | ## Chaining to -Chaining from other `ImageQuery` requires passing `IMAGE_QUERY` or any of the aliases mentioned above as the `query_type` +Chaining from other `ImageQuery` requires passing `image_query` or any of the aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|---------------|---------------------|----------------------|-------------|--------------------------| -| `ServerQuery` | ImageQuery.IMAGE_ID | ServerQuery.IMAGE_ID | Many-to-One | [SERVERS.md](SERVERS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|---------------|--------|------------|-------------|--------------------------| +| `ServerQuery` | "id" | "image_id" | Many-to-One | [SERVERS.md](SERVERS.md) | ## run() meta-parameters @@ -82,7 +76,7 @@ Chaining from other `ImageQuery` requires passing `IMAGE_QUERY` or any of the al | `as_admin: Bool` | Yes, default = False | If True, will run the query as an admin - this may be required to query outside of given project context set in clouds.yaml.

Make sure that the clouds.yaml context user has admin privileges | -To query on all projects remember to call `run()` like so: +To query on all projects call `run()` like so: ```python ImageQuery.run(as_admin=True, all_projects=True) ``` diff --git a/docs/user_docs/query_docs/PROJECTS.md b/docs/user_docs/query_docs/PROJECTS.md index bfe80b5..f9396a0 100644 --- a/docs/user_docs/query_docs/PROJECTS.md +++ b/docs/user_docs/query_docs/PROJECTS.md @@ -9,34 +9,26 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/identity/v3/index.html#p To Query for Projects using the Query Library, you can import `ProjectQuery()` like so: ```python -from openstack_query import ProjectQuery +from openstackquery import ProjectQuery ``` `ProjectQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `ProjectQuery` is `ProjectProperties`. You can import `ProjectProperties` like so: +A `Project` has the following properties: -```python -from enums.query.props.project_properties import ProjectProperties -``` - -`ProjectProperties` exposes the following properties: - - -| Property Enum | Type | Aliases | Description | -|---------------------|----------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| PROJECT_DESCRIPTION | `string` | "description", "desc" | The description of the project. | -| PROJECT_DOMAIN_ID | `string` | "domain_id" | The ID of the domain which owns the project. | -| PROJECT_ID | `string` | "project_id" | Unique ID Openstack has assigned the project. | -| PROJECT_IS_DOMAIN | `bool` | "is_domain" | Indicates whether the project also acts as a domain.
If set to True, the project acts as both a project and a domain. | -| PROJECT_IS_ENABLED | `bool` | "is_enabled" | Indicates whether users can authorize against this project.
if set to False, users cannot access project, additionally all authorized tokens are invalidated. | -| PROJECT_NAME | `string` | "name" | Name of the project. | -| PROJECT_PARENT_ID | `string` | "parent_id" | The ID of the parent of the project. | +| Return Type | Property Name(s) (case-insensitive) | Description | +|-------------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `string` | "description", "desc" | The description of the project. | +| `string` | "domain_id" | The ID of the domain which owns the project. | +| `string` | "project_id" | Unique ID Openstack has assigned the project. | +| `bool` | "is_domain" | Indicates whether the project also acts as a domain.
If set to True, the project acts as both a project and a domain. | +| `bool` | "is_enabled" | Indicates whether users can authorize against this project.
if set to False, users cannot access project, additionally all authorized tokens are invalidated. | +| `string` | "name" | Name of the project. | +| `string` | "parent_id" | The ID of the parent of the project. | Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc -Alternatively, you can pass property aliases (passed as string) instead (currently WIP) ## Chaining This section details valid mappings you can use to chain onto other queries or from other queries to chain into a `ProjectQuery` object. @@ -45,9 +37,9 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|--------------------------|---------------------------| -| QueryTypes.PROJECT_QUERY | "project", "projects" | +| Aliases (case-insensitive | +|--------------------------------------------------------| +| "project", "projects", "project_query", "projectquery" | @@ -56,17 +48,17 @@ A `ProjectQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | -|------------------------------|-----------------------------|-------------|---------------------------------| -| ProjectProperties.PROJECT_ID | ServerProperties.PROJECT_ID | One-to-Many | `ProjectQuery` to `ServerQuery` | +| Prop 1 | Prop 2 | Type | Maps | +|--------|--------------|-------------|---------------------------------| +| "id" | "project_id" | One-to-Many | `ProjectQuery` to `ServerQuery` | ## Chaining to Chaining from other `ProjectQuery` requires passing `PROJECT_QUERY` or any aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|---------------|-----------------------------|------------------------------|-------------|--------------------------| -| `ServerQuery` | ServerProperties.PROJECT_ID | ProjectProperties.PROJECT_ID | Many-to-One | [SERVERS.md](SERVERS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|---------------|--------------|--------|-------------|--------------------------| +| `ServerQuery` | "project_id" | "id" | Many-to-One | [SERVERS.md](SERVERS.md) | ## run() meta-parameters diff --git a/docs/user_docs/query_docs/SERVERS.md b/docs/user_docs/query_docs/SERVERS.md index f15f986..df09e1c 100644 --- a/docs/user_docs/query_docs/SERVERS.md +++ b/docs/user_docs/query_docs/SERVERS.md @@ -12,40 +12,32 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/identity/v3/index.html#s To Query for Servers using the Query Library, you can import `ServerQuery()` like so: ```python -from openstack_query import ServerQuery +from openstackquery import ServerQuery ``` `ServerQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `ServerQuery` is `ServerProperties`. You can import `ServerProperties` like so: - -```python -from enums.query.props.server_properties import ServerProperties -``` - -`ServerProperties` exposes the following properties: - -| Property Enum | Type | Aliases | Description | -|--------------------------|--------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| FLAVOR_ID | `string` | `None` | The ID of the Flavor the Server is using | -| HYPERVISOR_NAME | `string` | `None` | Name of the Hypervisor the Server is being hosted on | -| IMAGE_ID | `string` | `None` | The ID of the Image the Server is using | -| PROJECT_ID | `string` | `None` | The ID of the Project the Server is associated with | -| SERVER_CREATION_DATE | `string` (x) | "created_at" | Timestamp of when the server was created. | -| SERVER_DESCRIPTION | `string` | "description", "desc" | User provided description of the server. | -| SERVER_ID | `string` | "id", "uuid" | Unique ID Openstack has assigned the server. | -| SERVER_LAST_UPDATED_DATE | `string` (x) | "updated_at" | Timestamp of when this server was last updated. | -| SERVER_NAME | `string` | "vm_name", name" | User provided name for server | -| SERVER_STATUS | `string` | "vm_status", "status" | The state this server is in. Valid values include
ACTIVE, BUILDING, DELETED, ERROR, HARD_REBOOT, PASSWORD, PAUSED,
REBOOT, REBUILD, RESCUED, RESIZED, REVERT_RESIZE, SHUTOFF, SOFT_DELETED, STOPPED, SUSPENDED, UNKNOWN, or VERIFY_RESIZE. | -| USER_ID | `string` | `None` | The ID of the User that owns the server | -| ADDRESSES | `string` | "ips", "vm_ips", "server_ips" | Comma-separated list of IP addresses this server can be accessed through | +A `Server` has the following properties: + +| Return Type | Property Name(s) (case-insensitive) | Description | +|--------------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `string` | `"flavor_id"` | The ID of the Flavor the Server is using | +| `string` | `"hypervisor_name"` | Name of the Hypervisor the Server is being hosted on | +| `string` | `"image_id"` | The ID of the Image the Server is using | +| `string` | `"project_id"` | The ID of the Project the Server is associated with | +| `string` (x) | `"created_at"` | Timestamp of when the server was created. | +| `string` | `"description"`, `"desc"` | User provided description of the server. | +| `string` | `"id"`, `"uuid"` | Unique ID Openstack has assigned the server. | +| `string` (x) | `"updated_at"` | Timestamp of when this server was last updated. | +| `string` | `"vm_name"`, `"name"` | User provided name for server | +| `string` | `"vm_status"`, `"status"` | The state this server is in. Valid values include
ACTIVE, BUILDING, DELETED, ERROR, HARD_REBOOT, PASSWORD, PAUSED,
REBOOT, REBUILD, RESCUED, RESIZED, REVERT_RESIZE, SHUTOFF, SOFT_DELETED, STOPPED, SUSPENDED, UNKNOWN, or VERIFY_RESIZE. | +| `string` | `"user_id"` | The ID of the User that owns the server | +| `string` | `"ips"`, `"vm_ips"`, `"server_ips"` | Comma-separated list of IP addresses this server can be accessed through | (x) - These are UTC timestamps in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format - Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc -Alternatively, you can pass property aliases (passed as string) instead (currently WIP) ## Chaining This section details valid mappings you can use to chain onto other queries or from other queries to chain into a `ProjectQuery` object. @@ -54,35 +46,35 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|-------------------------|---------------------------| -| QueryTypes.SERVER_QUERY | "server", "servers" | +| Aliases (case-insensitive) | +|----------------------------------------------------| +| "server", "servers", "server_query", "serverquery" | ## Chaining from A `ServerQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | Documentation | -|--------------------------------|------------------------------------|-------------|------------------------------------|----------------------------------| -| ServerProperties.USER_ID | UserProperties.USER_ID | Many-to-One | `ServerQuery` to `UserQuery` | [USERS.md](USERS.md) | -| ServerProperties.PROJECT_ID | ProjectProperties.PROJECT_ID | Many-to-One | `ServerQuery` to `ProjectQuery` | [PROJECTS.md](PROJECTS.md) | -| ServerProperties.FLAVOR_ID | FlavorProperties.FLAVOR_ID | Many-to-One | `ServerQuery` to `FlavorQuery` | [FLAVORS.md](FLAVORS.md) | -| ServerProperties.IMAGE_ID | ImageProperties.IMAGE_ID | Many-to-One | `ServerQuery` to `ImageQuery` | [IMAGES.md](IMAGES.md) | -| ServerProperties.HYPERVISOR_NAME | HypervisorProperties.HYPERVISOR_NAME | Many-to-One | `ServerQuery` to `HypervisorQuery` | [HYPERVISORS.md](HYPERVISORS.md) | +| Prop 1 | Prop 2 | Type | Maps | Documentation | +|---------------------|----------|-------------|------------------------------------|----------------------------------| +| `"user_id"` | `"id"` | Many-to-One | `ServerQuery` to `UserQuery` | [USERS.md](USERS.md) | +| `"project_id"` | `"id"` | Many-to-One | `ServerQuery` to `ProjectQuery` | [PROJECTS.md](PROJECTS.md) | +| `"flavor_id"` | `"id"` | Many-to-One | `ServerQuery` to `FlavorQuery` | [FLAVORS.md](FLAVORS.md) | +| `"image_id"` | `"id"` | Many-to-One | `ServerQuery` to `ImageQuery` | [IMAGES.md](IMAGES.md) | +| `"hypervisor_name"` | `"name"` | Many-to-One | `ServerQuery` to `HypervisorQuery` | [HYPERVISORS.md](HYPERVISORS.md) | ## Chaining to Chaining from other `ServerQuery` requires passing `SERVER_QUERY` or any aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|-------------------|------------------------------------|-----------------------------|-------------|----------------------------------| -| `UserQuery` | UserProperties.USER_ID | ServerProperties.USER_ID | One-to-Many | [USERS.md](USERS.md) | -| `ProjectQuery` | ProjectProperties.PROJECT_ID | ServerProperties.PROJECT_ID | One-to-Many | [PROJECTS.md](PROJECTS.md) | -| `FlavorQuery` | FlavorProperties.FLAVOR_ID | ServerProperties.FLAVOR_ID | One-to-Many | [FLAVORS.md](FLAVORS.md) | -| `ImageQuery` | ImageProperties.IMAGE_ID | ServerProperties.IMAGE_ID | Many-to-One | [IMAGES.md](IMAGES.md) | -| `HypervisorQuery` | HypervisorProperties.HYPERVISOR_ID | ServerProperties.FLAVOR_ID | One-to-Many | [HYPERVISORS.md](HYPERVISORS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|-------------------|--------|---------------------|-------------|----------------------------------| +| `UserQuery` | `id` | `"user_id"` | One-to-Many | [USERS.md](USERS.md) | +| `ProjectQuery` | `id` | `"project_id"` | One-to-Many | [PROJECTS.md](PROJECTS.md) | +| `FlavorQuery` | `id` | `"flavor_id"` | One-to-Many | [FLAVORS.md](FLAVORS.md) | +| `ImageQuery` | `id` | `"image_id"` | Many-to-One | [IMAGES.md](IMAGES.md) | +| `HypervisorQuery` | `name` | `"hypervsior_name"` | One-to-Many | [HYPERVISORS.md](HYPERVISORS.md) | ## run() meta-parameters diff --git a/docs/user_docs/query_docs/USERS.md b/docs/user_docs/query_docs/USERS.md index 149f95e..9bdbdec 100644 --- a/docs/user_docs/query_docs/USERS.md +++ b/docs/user_docs/query_docs/USERS.md @@ -10,32 +10,26 @@ See [Openstack Docs](https://docs.openstack.org/api-ref/identity/v3/index.html#u To Query for Users using the Query Library, you can import `UserQuery()` like so: ```python -from openstack_query import UserQuery +from openstackquery import UserQuery ``` `UserQuery()` can then be used to setup and run queries - see [API.md](../API.md) for details on API calls ## Properties -The Valid property enum for `UserQuery` is `UserProperties`. You can import `UserProperties` like so: -```python -from enums.query.props.user_properties import UserProperties -``` +A `User` has the following properties: -`UserProperties` exposes the following properties: - -| Property Enum | Type | Aliases | Description | -|------------------|----------|--------------------------------------------------------------|-------------------------------------------| -| USER_DOMAIN_ID | `string` | "domain_id" | The ID for the domain which owns the user | -| USER_DESCRIPTION | `string` | "description", "desc" | The description of this user. | -| USER_EMAIL | `string` | "email", "email_addr", "email_address", "user_email_address" | The email address of this user. | -| USER_ID | `string` | "id", "uuid" | Unique ID Openstack has assigned the user | -| USER_NAME | `string` | "name", "username | Unique user name (within the domain) | +| Return Type | Property Name(s) (case-insensitive) | Description | +|-------------|--------------------------------------------------------------|-------------------------------------------| +| `string` | "domain_id" | The ID for the domain which owns the user | +| `string` | "description", "desc" | The description of this user. | +| `string` | "email", "email_addr", "email_address", "user_email_address" | The email address of this user. | +| `string` | "id", "uuid" | Unique ID Openstack has assigned the user | +| `string` | "name", "username | Unique user name (within the domain) | Any of these properties can be used for any of the API methods that takes a property - like `select`, `where`, `sort_by` etc -Alternatively, you can pass property aliases (passed as string) instead (currently WIP) ## Chaining This section details valid mappings you can use to chain onto other queries or from other queries to chain into a `ProjectQuery` object. @@ -45,33 +39,32 @@ This applies to API calls `then` and `append_from` - see [API.md](../API.md) for ## Query Alias The aliases that can be used for the query when chaining are listed below: -| Query Enum | Aliases (case-insensitive | -|-----------------------|---------------------------| -| QueryTypes.USER_QUERY | "user", "users" | - +| Aliases (case-insensitive) | +|--------------------------------------------| +| "user", "users", "user_query", "userquery" | ## Chaining from A `UserQuery` can be chained to other queries. The following shared-common properties are listed below (as well as the Query object they map to): -| Prop 1 | Prop 2 | Type | Maps | -|------------------------|--------------------------|-------------|------------------------------| -| UserProperties.USER_ID | ServerProperties.USER_ID | One-to-Many | `UserQuery` to `ServerQuery` | +| Prop 1 | Prop 2 | Type | Maps | +|--------|-------------|-------------|------------------------------| +| `"id"` | `"user_id"` | One-to-Many | `UserQuery` to `ServerQuery` | ## Chaining to Chaining from other `UserQuery` requires passing `USER_QUERY` or any aliases mentioned above as the `query_type` -| From | Prop 1 | Prop 2 | Type | Documentation | -|---------------|--------------------------|------------------------|-------------|--------------------------| -| `ServerQuery` | ServerProperties.USER_ID | UserProperties.USER_ID | Many-to-One | [SERVERS.md](SERVERS.md) | +| From | Prop 1 | Prop 2 | Type | Documentation | +|---------------|-------------|--------|-------------|--------------------------| +| `ServerQuery` | `"user_id"` | `"id"` | Many-to-One | [SERVERS.md](SERVERS.md) | ## run() meta-parameters `UserQuery()` has the following meta-parameters that can be used when calling `run()` to fine-tune the query. -| Parameter Definition | Optional? | Description | -|------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `from_domain: UserDomains`

(see `/enums/user_domains`) | Yes | A User Domain to limit User query to
Optional, if not given will run search on DEFAULT_DOMAIN - `UserDomains.STFC`

NOTE: it is possible to specify user domain via `where()` - if both are provided then an error is raised) | +| Parameter Definition | Optional? | Description | +|----------------------|-----------|-----------------------------------------------------------------------------------------------------------------| +| `from_domain: str` | Yes | A User Domain to limit User query to
Optional, if not given will run search on domain with name `"default"` | diff --git a/openstackquery/enums/query_presets.py b/openstackquery/enums/query_presets.py index 6ef986d..08a8bad 100644 --- a/openstackquery/enums/query_presets.py +++ b/openstackquery/enums/query_presets.py @@ -44,7 +44,12 @@ def _get_aliases(): """ A method that returns all valid string alias mappings """ - return {} + return { + QueryPresetsInteger.LESS_THAN: ["<"], + QueryPresetsInteger.GREATER_THAN: [">"], + QueryPresetsInteger.GREATER_THAN_OR_EQUAL_TO: [">="], + QueryPresetsInteger.LESS_THAN_OR_EQUAL_TO: ["<="], + } class QueryPresetsDateTime(EnumWithAliases): @@ -62,7 +67,12 @@ def _get_aliases(): """ A method that returns all valid string alias mappings """ - return {} + return { + QueryPresetsDateTime.YOUNGER_THAN: ["<"], + QueryPresetsDateTime.OLDER_THAN: [">"], + QueryPresetsDateTime.OLDER_THAN_OR_EQUAL_TO: [">="], + QueryPresetsDateTime.YOUNGER_THAN_OR_EQUAL_TO: ["<="], + } class QueryPresetsString(EnumWithAliases): diff --git a/openstackquery/enums/query_types.py b/openstackquery/enums/query_types.py index b259296..8a93cb9 100644 --- a/openstackquery/enums/query_types.py +++ b/openstackquery/enums/query_types.py @@ -31,16 +31,31 @@ def _get_aliases() -> Dict: QueryTypes.FLAVOR_QUERY: [ "flavor", "flavors", + "flavorquery", ], QueryTypes.PROJECT_QUERY: [ "project", "projects", + "projectquery", ], QueryTypes.SERVER_QUERY: [ "server", "servers", + "serverquery", + ], + QueryTypes.USER_QUERY: [ + "user", + "users", + "userquery", + ], + QueryTypes.IMAGE_QUERY: [ + "image", + "images", + "imagequery", + ], + QueryTypes.HYPERVISOR_QUERY: [ + "hypervisor", + "hypervisors", + "hypervisorquery", ], - QueryTypes.USER_QUERY: ["user", "users"], - QueryTypes.IMAGE_QUERY: ["image", "images"], - QueryTypes.HYPERVISOR_QUERY: ["hypervisor", "hypervisors"], } diff --git a/tests/enums/test_query_presets.py b/tests/enums/test_query_presets.py index c6aedd0..a017c2d 100644 --- a/tests/enums/test_query_presets.py +++ b/tests/enums/test_query_presets.py @@ -36,7 +36,7 @@ def test_not_equal_to_serialization(preset_string): @pytest.mark.parametrize( - "preset_string", ["greater_than", "Greater_Than", "GrEaTer_ThAn"] + "preset_string", ["greater_than", "Greater_Than", "GrEaTer_ThAn", ">"] ) def test_greater_than_serialization(preset_string): """ @@ -54,6 +54,7 @@ def test_greater_than_serialization(preset_string): "greater_than_or_equal_to", "Greater_Than_Or_Equal_To", "GrEaTer_ThAn_Or_EqUaL_tO", + ">=", ], ) def test_greater_than_or_equal_to_serialization(preset_string): @@ -66,7 +67,7 @@ def test_greater_than_or_equal_to_serialization(preset_string): ) -@pytest.mark.parametrize("preset_string", ["less_than", "Less_Than", "LeSs_ThAn"]) +@pytest.mark.parametrize("preset_string", ["less_than", "Less_Than", "LeSs_ThAn", "<"]) def test_less_than_serialization(preset_string): """ Tests that variants of LESS_THAN can be serialized @@ -78,7 +79,7 @@ def test_less_than_serialization(preset_string): @pytest.mark.parametrize( "preset_string", - ["less_than_or_equal_to", "Less_Than_Or_Equal_To", "LeSs_ThAn_Or_EqUaL_tO"], + ["less_than_or_equal_to", "Less_Than_Or_Equal_To", "LeSs_ThAn_Or_EqUaL_tO", "<="], ) def test_less_than_or_equal_to_serialization(preset_string): """ @@ -90,7 +91,9 @@ def test_less_than_or_equal_to_serialization(preset_string): ) -@pytest.mark.parametrize("preset_string", ["older_than", "Older_Than", "OlDeR_ThAn"]) +@pytest.mark.parametrize( + "preset_string", ["older_than", "Older_Than", "OlDeR_ThAn", ">"] +) def test_older_than_serialization(preset_string): """ Tests that variants of OLDER_THAN can be serialized @@ -103,7 +106,12 @@ def test_older_than_serialization(preset_string): @pytest.mark.parametrize( "preset_string", - ["older_than_or_equal_to", "Older_Than_Or_Equal_To", "OlDeR_ThAn_Or_EqUaL_To"], + [ + "older_than_or_equal_to", + "Older_Than_Or_Equal_To", + "OlDeR_ThAn_Or_EqUaL_To", + ">=", + ], ) def test_older_than_or_equal_to_serialization(preset_string): """ @@ -116,7 +124,7 @@ def test_older_than_or_equal_to_serialization(preset_string): @pytest.mark.parametrize( - "preset_string", ["younger_than", "Younger_Than", "YoUnGeR_ThAn"] + "preset_string", ["younger_than", "Younger_Than", "YoUnGeR_ThAn", "<"] ) def test_younger_than_serialization(preset_string): """ @@ -134,6 +142,7 @@ def test_younger_than_serialization(preset_string): "younger_than_or_equal_to", "Younger_Than_Or_Equal_To", "YoUngEr_ThAn_Or_EqUaL_To", + "<=", ], ) def test_younger_than_or_equal_to_serialization(preset_string): diff --git a/tests/enums/test_query_types.py b/tests/enums/test_query_types.py index 1789c5c..99666d2 100644 --- a/tests/enums/test_query_types.py +++ b/tests/enums/test_query_types.py @@ -12,6 +12,7 @@ "flavor_query", "flavor", "flavors", + "flavorquery", ], ) def test_flavor_query_serialization(query_type): @@ -29,6 +30,7 @@ def test_flavor_query_serialization(query_type): "server_query", "server", "servers", + "serverquery", ], ) def test_server_query_serialization(query_type): @@ -46,6 +48,7 @@ def test_server_query_serialization(query_type): "project_query", "project", "projects", + "projectquery", ], ) def test_project_query_serialization(query_type): @@ -57,13 +60,7 @@ def test_project_query_serialization(query_type): @pytest.mark.parametrize( "query_type", - [ - "User_Query", - "UsEr_QuEry", - "user_query", - "user", - "users", - ], + ["User_Query", "UsEr_QuEry", "user_query", "user", "users", "userquery"], ) def test_user_query_serialization(query_type): """ @@ -74,13 +71,7 @@ def test_user_query_serialization(query_type): @pytest.mark.parametrize( "query_type", - [ - "Image_Query", - "ImAgE_QuEry", - "image_query", - "image", - "images", - ], + ["Image_Query", "ImAgE_QuEry", "image_query", "image", "images", "imagequery"], ) def test_image_query_serialization(query_type): """ @@ -97,6 +88,7 @@ def test_image_query_serialization(query_type): "hypervisor_query", "hypervisor", "hypervisors", + "hypervisorquery", ], ) def test_hypervisor_query_serialization(query_type):