## Title
QSEA refers to the Qlik Sense Engine API.
## Description
QSEA is designed to automate basic operations with Qlik Sense Enterprise apps in a Pythonic way. With QSEA, you can quickly view and edit variables, master measures, dimensions and sheet charts. For example, you can replace variables in all master measures of your app with just one line of code:
```python
for ms in App.measures: ms.update(definition = replace(ms.definition, '$(var1)', '$(var2)'))
```
or quickly move all measures from one app to another:
```python
for ms in source_app.measures: ms.copy(target_app)
```
or copy a sheet with all charts from one app to another:
```python
source_app.sheets['Source_sheet_name'].copy(target_app)
```
## Installation
```python
pip install qsea
```
## Table of Contents
- [Getting started](#getting-started)
- [Full Guide](#full-guide)
- [App class](#app-class)
- [App.load()](#appload)
- [App.save()](#appsave)
- [App.reload_data()](#appreload_data)
- [App.children](#appchildren)
- [AppChildren class](#appchildren-class)
- [AppChildren add](#appchildrenadd)
- [Variable class](#variable-class)
- [Variable properties](#variable-properties)
- [Variable.update()](#variableupdate)
- [Variable.delete()](#variabledelete)
- [Variable.rename()](#variablerename)
- [Variable.get_layout()](#variableget_layout)
- [Measure class](#measure-class)
- [Measure properties](#measure-properties)
- [Measure.copy()](#measurecopy)
- [Measure.update()](#measureupdate)
- [Measure.delete()](#measuredelete)
- [Measure.rename()](#measurerename)
- [Measure.get_layout()](#measureget_layout)
- [Measure.get_properties()](#measureget_properties)
- [Dimension class](#dimension-class)
- [Dimension properties](#dimension-properties)
- [Dimension.copy()](#dimensioncopy)
- [Dimension.update()](#dimensionupdate)
- [Dimension.delete()](#dimensiondelete)
- [Dimension.rename()](#dimensionrename)
- [Dimension.get_layout()](#dimensionget_layout)
- [Sheet class](#sheet-class)
- [Sheet properties](#sheet-properties)
- [Sheet.copy()](#sheetcopy)
- [Sheet.load()](#sheetload)
- [Sheet.clear()](#sheetclear)
- [Sheet.get_layout()](#sheetget_layout)
- [Field class](#field-class)
- [Field properties](#field-properties)
- [Bookmark class](#bookmark-class)
- [Bookmark properties](#bookmark-properties)
- [Object class](#object-class)
- [Object properties](#object-properties)
- [Object.export_data()](#objectexport_data)
- [Object.copy()](#objectcopy)
- [Object.load()](#objectload)
- [Object.get_layout()](#objectget_layout)
- [ObjectChildren class](#objectchildren-class)
- [ObjectMeasure class](#objectmeasure-class)
- [ObjectMeasure properties](#objectmeasure-properties)
- [ObjectMeasure.update()](#objectmeasureupdate)
- [ObjectMeasure.delete()](#objectmeasuredelete)
- [ObjectDImension class](#objectdimension-class)
- [ObjectDimension properties](#objectdimension-properties)
- [ObjectDimension.update()](#objectdimensionupdate)
- [ObjectDimension.delete()](#objectdimensiondelete)
- [Roadmap](#roadmap)
- [License](#license)
## Getting started
QSEA uses the Qlik Sense Engine API via the Qlik Sense Proxy Service as its main tool, so you'll need a Virtual Proxy and a JWT key to start working with QSEA. Please refer to the following links for help.
How to set up JWT authentication
https://community.qlik.com/t5/Official-Support-Articles/Qlik-Sense-How-to-set-up-JWT-authentication/ta-p/1716226
Setting up a Virtual Proxy
https://help.qlik.com/en-US/sense-admin/February2024/Subsystems/DeployAdministerQSE/Content/Sense_DeployAdminister/QSEoW/Administer_QSEoW/Managing_QSEoW/create-virtual-proxy.htm
Your credentials should look something like this
```python
header_user = {'Authorization': 'Bearer <Very long API KEY>'}
qlik_url = "wss://server.domain.com[/virtual proxy]/app/"
```
Now we can connect to the Qlik Server:
```python
conn = qsea.Connection(header_user, qlik_url)
```
Let's create an App object, which represents the application in Qlik Sense.
```python
app = qsea.App(conn, 'MyAppName')
```
By default the App class object is almost empty. Use the `load()` function to make use of it:
```python
app.load()
```
Now all variables, master measures, and dimensions are uploaded to our App object. We can access them by their name:
```python
var = app.variables['MyVar']
var.definition
```
```python
ms = app.measures['MyMeasure']
ms.label_expression
```
Or, we can overview their properties via a pandas DataFrame.
```python
app.dimensions.df
```
Let's create a new measure:
```python
app.measures.add(name = 'MyMeasure', definition = 'sum(Sales)')
```
or update a variable:
```python
var.update(definition = 'sum(Sales)')
```
Save the app to ensure that the changes are reflected in the real Qlik Sense application.
```python
app.save()
```
Let's copy the set of master dimensions into a new app:
```python
source_app = qsea.App(conn, 'Source AppName')
target_app = qsea.App(conn, 'Target AppName')
source_app.dimensions.load()
target_app.dimensions.load()
for dim in source_app.dimensions:
if dim.name not in [target_dim.name for target_dim in target_app.dimensions]:
dim.copy(target_app = target_app)
target_app.save()
```
Besides master measures, master dimensions, and variables, tables and charts in the App can also be uploaded.
```python
app.load()
sh = app.sheets['MySheet']
sh.load()
for obj in sh.objects:
obj.load()
for ms on obj.measures:
print(ms.definition)
```
Objects and entire sheets can be copied to another app. While it is possible to copy sheets via the Qlik Sense interface, in some cases this can cause problems if the set of the master measures/dimensions in the source and target apps are different. Qsea allows to choose whether to match master measure IDs or names.
```python
source_app = qsea.App(conn, 'Source AppName')
target_app = qsea.App(conn, 'Target AppName')
source_app.load()
target_app.load()
source_sh = source_app.sheets['SheetToCopy']
source_sh.copy(target_app = target_app)
source_obj = source_app.sheets['SheetWithObject'].objects['SourceObjectID']
source_obj.copy(target_app = target_app, target_sheet = target_app.sheets['TargetSheet'])
target_app.save()
```
For unknown reasons, on certain instances of Qlik Sense, changes in the App may not be visible in the Qlik Sense interface. The usual workaround is to make a new copy of the Application (via QMC or Hub). Usually, all changes can be seen in the copy.
Note that as it stands, only basic properties, such as names, definitions, and a couple of others, can be accessed via the qsea module.
Most read-only operations (such as loading apps) can be performed on published apps. However, it is recommended to modify objects only in unpublished apps.
It's highly recommended to make a backup copy of your application.
Good luck!
## Full Guide
### Connection class
The class that represents a dictionary of websocket connections to Qlik Sense Engine API
Since one websocket connection can be used only for one app, this class is used to handle all websocket connections
New websocket connections are created automatically when a new app object is created
Note that the Qlik Sense Engine API has a limit of active parallel connections. Since there is no way to terminate the existing connection (except restarting the proxy server that is generally unacceptable), one have to wait for the Qlik Sense Engine to terminate some of the old sessions.
There is no way to reconnect to an existing connection if the Connection class object is recreated. Thus, it is highly recommended to avoid recreating the Connection class object in order to avoid reaching the limit of active connections.
### App class
The class, representing the Qlik Sense application. This is the main object to work with. The class is empty when created; run the `load()` function to make use of it.
#### App.load()
Loads data from the Qlik Sense application into an App object.
Args:
* depth (int): depth of loading
- 1 - app + variables, measures, sheets, fields, dimensions (default value)
- 2 - everything from 1 + sheet objects (tables, sharts etc.)
- 3 - everything from 2 + object dimensions and measures
Different levels can be useful when working with large apps, as a full load can be time-consuming. Only dimensions and measures from standard Qlik Sense charts are uploaded. Uploading dimensions from filter panes is currently not supported.
```python
App.load(level = 3)
```
#### App.save()
You have to save the App object for the changes to be reflected in the Qlik Sense Application. Note that it is recommended to modify objects only in unpublished apps.
```python
App.save()
```
#### App.reload_data()
Starts the script of reloading data into the Qlik Sense Application.
```python
App.reload_data()
```
#### App.children
app.load(level = 1) creates several objects of AppChildren class
### AppChildren class
The class contains collections of master objects in the Qlik Sense Application:
* `app.variables`: a collection of Variable class objects, representing the variables of the Qlik Sense application
* `app.measures`: a collection of Measure class objects, representing the master measures of the Qlik Sense application
* `app.dimensions`: a collection of Dimension class objects, representing the master dimensions of the Qlik Sense application
* `app.sheets`: a collection of Sheet class objects, representing the sheets of the Qlik Sense application
* `app.fields`: a collection of Field class objects, representing the fields of the Qlik Sense application
You can access the main information about each group of objects in a pandas DataFrame via the `.df` attribute:
```python
app.variables.df
app.measures.df
```
#### AppChildren.add()
Use the `add()` function to add new variables, master measures, master dimensions or sheets to the app.
Args:
* name (str): Name of the object to be created.
* definition (str): Definition of the object to be created.
* description (str, optional): Description of the object to be created. Defaults to ''.
* label (str, optional): Label of the object to be created. Defaults to ''.
* label_expression (str, optional): Label expression of the object to be created. Defaults to ''.
* format_type (str, optional): Format type of the object to be created. Defaults to 'U'.
- 'U' for auto
- 'F' for number
- 'M' for money
- 'D' for date
- 'IV' for duration
- 'R' for other
* format_ndec (int, optional): Number of decimals of the object to be created. Defaults to 10.
* format_use_thou (int, optional): Use thousands separator for the object to be created. Defaults to 0.
* format_dec (str, optional): Decimal separator for the object to be created. Defaults to ','.
* format_thou (str, optional): Thousands separator for the object to be created. Defaults to ''.
* base_color (str, optional): Base color (hex) for the object to be created. Defaults to None.
* source (variable, measure or dimension, optional): Source object for the object to be created. Defaults to None.
Returns: ID of the object created, if created successfully, None otherwise.
Only parameters applicable to the specific class will be used
```python
app.variables.add(name = 'MyVar', definition = 'sum(Sales)')
app.measures.add(name = 'MyFunc', definition = 'sum(Sales)', format_type = 'F')
app.dimensions.add(name = 'MyDim', definition = 'Customer')
app.measures.add(source = App1.measures['MyFunc'])
app.sheets.add(name = 'MySheet')
```
### Variable class
The class represents variables of the application and is a member of the App.variables collection. You can access a specific variable by its name or iterate through them:
```python
var = app.variables['MyVar']
print(var.definition)
for var in app.variables:
if var.definition == 'sum(Sales)': var.update(name = 'varSales')
```
#### Variable properties
* name: this is the name of the variable you generally use in the Qlik Sense interface
* definition: the formula behind the variable
* description: the description of the variable
* auxiliary
- handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the variable via the `query()` function
- app_handle: the handle of the parent App object
- id: Qlik Sense internal id of the variable
- parent: App-children object; you can access the App class object like this `var.parent.parent`
- created_date: creation date of the variable, as stored in Qlik Sense
- modified_date: date of the last modification of the variable, as stored in Qlik Sense
- script_created: True if the variable is created via the application load script, False if not.
#### Variable.update()
Updates the variable on the Qlik Sense Server
Args:
* definition (str, optional): new definition of the variable (leave `None` to keep the old value)
* description (str, optional): new description of the variable (leave `None` to keep the old value)
Returns:
True if the variable was updated successfully, False otherwise
```python
var = app.variables['MyVar']
var.update(definition = 'sum(Sales)')
app.save()
```
#### Variable.delete()
Deletes the variable from the Qlik Sense Server
Returns:
True if the variable was deleted successfully, False otherwise
```python
var = app.variables['MyVar']
var.delete()
app.save()
```
#### Variable.rename()
Renames the variable on the Qlik Sense Server. Since there is no direct method to rename the variable, it essentially deletes the variable with the old name, and creates a new one, with the new name.
Returns:
True if the variable is renamed successfully, False otherwise
```python
var = app.variables['MyVar']
var.rename('MyVarNewName')
app.save()
```
#### Variable.get_layout()
Returns the json layout of the variable; a shortcut to the GetLayout method of the Engine API
```python
var.get_layout()
```
### Measure class
The class represents master measures of the application and is a member of the App.measures collection. You can access a specific measure by its name or iterate through them.
```python
ms = app.measures['MyMeasure']
print(ms.definition)
for ms in app.measures:
if ms.definition == 'sum(Sales)': ms.update(name = 'Sales')
```
#### Measure properties
* name: the name of the measure you generally use in the Qlik Sense interface
* definition: the formula behind the measure
* description: the description of the measure
* label: the label of the measure, as it appears in charts
* label_expression: the label expression of the measure
* format_type: Format type of the object
- 'U' for auto
- 'F' for number
- 'M' for money
- 'D' for date
- 'IV' for duration
- 'R' for other
* format_ndec: Number of decimals for the object
* format_use_thou: Use thousands separator for the object
* format_dec: Decimal separator for the object
* format_thou: Thousands separator for the object
* base_color: Base color (hex) of the object
* auxiliary
- handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the measure via the `query()` function
- app_handle: the handle of the parent App object
- id: Qlik Sense internal id of the measure
- parent: AppChildren object; you can access the App class object like this `ms.parent.parent`
- created_date: creation date of the measure, as stored in Qlik Sense
- modified_date: date of the last modification of the measure, as stored in Qlik Sense
#### Measure.copy()
Creates a copy of the master measure in another app
Args: target_app (App): The target app, where the measure will be copied
Returns: str: ID of the measure created if successful, None otherwise
#### Measure.update()
Updates the measure on the Qlik Sense Server
Args:
* definition (str, optional): The definition of the measure
* description (str, optional): the description of the measure
* label (str, optional): the label of the measure, as it appears in charts
* label_expression (str, optional): the label expression of the measure
* format_type (str, optional): Format type of the object to be created. Defaults to 'U'.
- 'U' for auto
- 'F' for number
- 'M' for money
- 'D' for date
- 'IV' for duration
- 'R' for other
* format_ndec (int, optional): Number of decimals for the object to be created. Defaults to 10.
* format_use_thou (int, optional): Use thousands separator for the object to be created. Defaults to 0.
* format_dec (str, optional): Decimal separator for the object to be created. Defaults to ','.
* format_thou (str, optional): Thousands separator for the object to be created. Defaults to ''.
* base_color (str, optional): Base color (hex) of the object to be created. Defaults to None.
Returns:
True if the measure was updated successfully, False otherwise
```python
ms = app.measures['MyMeasure']
ms.update(definition = 'sum(Sales)', label = 'Total Sales', format_type = 'F')
app.save()
```
#### Measure.delete()
Deletes the measure from the Qlik Sense Server
Returns:
True if the measure was deleted successfully, False otherwise
```python
ms = app.measures['MyMeasure']
ms.delete()
app.save()
```
#### Measure.rename()
Renames the measure on the Qlik Sense Server.
Returns:
True if the measure was renamed successfully, False otherwise
```python
ms = app.measures['MyMeasure']
ms.rename('MyMeasureNewName')
app.save()
```
#### Measure.get_layout()
Returns the json layout of the measure; a shortcut to the GetLayout method of the Engine API
```python
ms.get_layout()
```
#### Measure.get_properties()
Returns the json properties of the measure; a shortcut to the GetProperties method of the Engine API
```python
ms.get_properties()
```
### Dimension class
The class represents master dimensions of the application and is a member of the App.dimensions collection. You can access a specific dimension by its name or iterate through them. Note that hierarchical dimensions are not yet supported."
```python
dim = app.dimensions['MyDimension']
print(dim.definition)
for dim in app.dimensions:
if dim.definition == '[Customer]': dim.update(name = 'Customer_dimension')
```
#### Dimension properties
* name: the name of the dimension you generally use in the Qlik Sense interface
* definition: the formula behind the dimension
* label: the label of the dimension, as it appears in charts
* base_color: Base color (hex) of the object
* auxiliary
- handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the dimension via the `query()` function
- app_handle: the handle of the parent App object
- id: Qlik Sense internal id of the dimension
- parent: AppChildren object; you can access the App class object like this `dim.parent.parent`
- created_date: creation date of the dimension, as stored in Qlik Sense
- modified_date: date of the last modification of the dimension, as stored in Qlik Sense
#### Dimension.copy()
Creates a copy of the master dimension in another app
Args: target_app (App): The target app, where the dimension will be copied
Returns: str: ID of the dimension created if successful, None otherwise
#### Dimension.update()
Updates the dimension on the Qlik Sense Server
Args:
* definition (str, optional): The definition of the dimension
* label (str, optional): the label of the dimension, as it appears in charts
* base_color (str, optional): Base color (hex) of the object to be created. Defaults to None.
Returns:
True if the dimension was updated successfully, False otherwise
```python
dim = app.dimensions['MyDimension']
dim.update(definition = 'Customer', label = 'Customer_dimension')
app.save()
```
#### Dimension.delete()
Deletes the dimension from the Qlik Sense Server
Returns:
True if the dimension was deleted successfully, False otherwise
```python
dim = app.dimensions['MyDimension']
dim.delete()
app.save()
```
#### Dimension.rename()
Renames the dimension on the Qlik Sense Server.
Returns:
True if the dimension was renamed succesfully, False otherwise
```python
dim = app.dimensions['MyDimension']
dim.rename('MyDimensionNewName')
app.save()
```
#### Dimension.get_layout()
Returns the json layout of the dimension; a shortcut to the GetLayout method of the Engine API
```python
dim.get_layout()
```
### Sheet class
The class represents the sheets of the application and is a member of the App.sheets collection. You can access objects on the sheets, such as charts and tables, via the Sheet class object.
```python
for sh in app.sheets:
print(sh.name)
```
#### Sheet properties
* name: that's the name of the sheet
* description: the description of the sheet
* auxiliary
- handle: the internal handle of the object in Qlik Sense Engine API; can be used to access the sheet via the `query()` function
- app_handle: the handle of the parent App object
- id: Qlik Sense internal id of the sheet
- parent: AppChildren object; you can access the App class object like this `ms.parent.parent`
- created_date: creation date of the sheet, as stored in Qlik Sense
- modified_date: date of the last modification of the sheet, as stored in Qlik Sense
- published: True if the sheet is published, False if not
- approved: True if the sheet is approved, False if not
- owner_id: GUID of the owner of the sheet
- owner_name: name of the owner of the sheet
#### Sheet.copy()
Creates a copy of the sheet in another app
Args:
* target_app (App): The target app, where the sheet will be copied
* master_match (str): 'name' by default: master measures and dimensions in the new object are matched by name. If 'id', they are matched by id.
Returns: str: ID of the sheet created if successful, None otherwise
```python
source_app = qsea.App(conn, 'Source AppName')
target_app = qsea.App(conn, 'Target AppName')
source_app.load()
target_app.load()
source_sh = source_app.sheets['SheetToCopy']
source_sh.copy(target_app = target_app)
```
Note: Some objects, not accessible via API (such as buttons) are not copied. Copying of conatainers and filterpanes is not supported. Master objects can be copied correctly only if they have 1-1 correspondence between the source and target apps and have the same IDs. It can be used as a workaround for the filterpane copy problem in some cases.
#### Sheet.load()
Loads objects from the sheet in a Qlik Sense application into a Sheet class object
```python
sh = App.sheets['MySheet']
sh.load()
for obj in sh.objects:
print(obj.type)
```
#### Sheet.clear()
Clears all objects from the sheet in a Qlik Sense application
#### Sheet.get_layout()
Returns the json layout of the sheet; a shortcut to the GetLayout method of the Engine API
```python
sh.get_layout()
```
### Field class
The class represents the fields of the application and is a member of the App.fields collection. You can only use the class for information purposes; no changes can be made with fields via QSEA.
```python
for fld in app.fields:
print(field.table_name, field.name)
```
#### Field properties
* name: name of the field, as it appears in the model
* table_name: name of the table, containing the field
* information_density, non_nulls, rows_count, subset_ratio, distinct_values_count, present_distinct_values, key_type, tags: properties of the fields as they can be found in the data model
* auxiliary
- handle: internal handle of the field object
- app_handle: handle of the parent App object
### Bookmark class
The class represents the bookmarks of the application and is a member of the App.bookmarks collection. You can only use the class for information purposes; no changes can be made with bookmarks via QSEA.
```python
for bm in app.bookmarks:
print(bm.name)
```
#### Bookmark properties
* name: name of the bookmark
* owner_id: GUID of the owner of the bookmark
* owner_user_id: user id of the owner of the bookmark
* owner_name: name of the owner of the bookmark
* description: description of the bookmark
* state_data: selection properties of the bookmark in JSON format; unfortionately, the whole list of selections can not be retrieved correctly
* auxiliary
- handle: internal handle of the bookmark object
- app_handle: handle of the parent App object
- id: Qlik Sense internal id of the bookmark
- parent: AppChildren object; you can access the App class object like this `ms.parent.parent`
- created_date: creation date of the bookmark, as stored in Qlik Sense
- modified_date: date of the last modification of the bookmark, as stored in Qlik Sense
- published: True if the bookmark is published, False if not
- approved: True if the bookmark is approved, False if not
### Object class
The class represents the objects on the sheet, such as charts and tables, and is a member of the SheetChildren collection.
#### Object properties
* type: type of the object, such as 'piechart' or 'pivot-table'
* col, row, colspan, rowspan, bounds_y, bounds_x, bounds_width, bounds_height: parameters referring to the location of an object on the sheet
* auxiliary
- handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the object via the `query()` function
- sheet_handle: handle of the parent sheet
- sheet: the Sheet object, on which the object itself is located
- id: Qlik Sense internal id of the object
- parent: SheetChildren object
#### Object.export_data()
Performs data export of an object (such as a table or chart) to an xslx or csv file.
Args:
* file_type (str, optional): 'xlsx' or 'csv', 'xlsx' by default
Returns: the path to the downloaded file in case of success, None if failed
#### Object.copy()
Creates a copy of the object in the specified sheet of another app
Args:
* target_app (App): The target app, where the sheet will be copied
* target_sheet (Sheet): The target sheet, where the object will be copied
* col (int, optional): The column number of the new object, None by default (the column of the source object is used)
* row (int, optional): The row number of the new object, None by default (the row of the source object is used)
* colspan (int, optional): The number of columns occupied by the new object, None by default (the colspan of the source object is used)
* rowspan (int, optional): The number of rows occupied by the new object, None by default (the rowspan of the source object is used)
* master_match (str): 'name' by default: master measures and dimensions in the new object are matched by name. If 'id', they are matched by id.
Returns: str: ID of the sheet created if successful, None otherwise
```python
source_object.copy(target_app, target_sheet)
```
#### Object.load()
Loads measures and dimensions of the object in a Qlik Sense application into an Object class instance.
```python
sh = App.sheets['MySheet']
sh.load()
for obj in sh.objects:
if obj.type == 'piechart':
obj.load()
print(obj.dimensions.count)
```
#### Object.get_layout()
Returns the json layout of the object; a shortcut to the GetLayout method of the Engine API
```python
obj.get_layout()
```
### ObjectChildren class
The class contains collections of measures and dimensions in the object on the sheet:
* `object.measures`: a collection of ObjectMeasure class objects, representing the measures in the object on the sheet
* `object.dimensions`: a collection of ObjectDimension class objects, representing the dimensions in the object on the sheet
* `object.subitems`: a collection of Object class objects, representing the subitems of filterpane and container type objects
You can access the main information in pandas DataFrame via `.df`:
```python
App.sheets['MySheet'].objects['object_id'].measures.df
```
Adding measures and dimensions to app objects is not supported yet.
### ObjectMeasure class
This class represents measures of the object on the sheet and is a member of the object.measures collection. Since there may be no specific name for the measure in the object, the internal Qlik ID is used instead of the name. Thus, you can either iterate through measures or call them by the internal Qlik ID:
```python
ms = obj.measures['measure_id']
print(ms.definition)
for ms in obj.measures:
if ms.definition == 'sum(Sales)': ms.update(definition = 'sum(Incomes)')
```
#### ObjectMeasure properties
* name: internal Qlik id of the measure
* definition: the formula behind the measure
* label: the label of the measure, as it appears in the charts
* label_expression: the label expression of the measure
* calc_condition: calculation condition for the measure
* library_id: if a master measure is used, this refers to its ID
* format_type: Format type of the object
- 'U' for auto
- 'F' for number
- 'M' for money
- 'D' for date
- 'IV' for duration
- 'R' for other
* format_ndec: Number of decimals of the object
* format_use_thou: Use thousands separator for the object
* format_dec: Decimal separator for the object
* format_thou: Thousands separator for the object
* auxiliary
- app_handle: the handle of the parent App object
- parent: ObjectChildren object
- object: you can access the Object class object like this `ms.object`
#### ObjectMeasure.update()
Updates the measure in the object on the sheet.
Args:
* definition (str, optional): The definition of the measure
* label (str, optional): the new label of the measure, as it appears in charts
* label_expression (str, optional): the label expression of the measure
* calc_condition (str, optional): calculation condition for the measure
* library_id (str, optional): id of the master measure
* format_type (str, optional): Format type of the object. Defaults to 'U'.
- 'U' for auto
- 'F' for number
- 'M' for money
- 'D' for date
- 'IV' for duration
- 'R' for other
* format_use_thou (int, optional): Use thousands separator for the object. Defaults to 0.
* format_dec (str, optional): Decimal separator for the object. Defaults to ','.
* format_thou (str, optional): Thousands separator for the object. Defaults to ''.
Returns:
True if the measure was updated successfully, False otherwise
```python
ms = obj.measures['measure_id']
ms.update(definition = 'sum(Sales)', label = 'Total Sales', format_type = 'F')
app.save()
```
#### ObjectMeasure.delete()
Deletes the measure from the object on the sheet
Returns:
True if the measure was deleted successfully, False otherwise
```python
ms = obj.measures['measure_id']
ms.delete()
app.save()
```
### ObjectDimension class
This class represents dimensions of the object on the sheet and is a member of the object.dimensions collection. Since there may be no specific name for the dimension in the object, the internal Qlik ID is used instead of the name. Thus, you can either iterate through dimensions or call them by the internal Qlik ID:
```python
dim = obj.measures['dimension_id']
print(dim.definition)
for dim in obj.dimensions:
if dim.definition == '[Customer]': dim.update(definition = '[Supplier]')
```
Note that hierarchical dimensions are not supported yet.
#### ObjectDimension properties
* name: internal Qlik id of the dimension
* definition: the formula behind the dimension
* label: the label of the dimension, as it appears in the charts
* auxiliary
- app_handle: the handle of the parent App object
- parent: ObjectChildren object
- object: you can access the Object class object like this `dim.object`
#### ObjectDimension.update()
Updates the dimension in the object on the sheet
Args:
* definition (str, optional): the definition of the dimension
* label (str, optional): the label of the dimension, as it appears in charts
* calc_condition (str, optional): calculation condition for the dimension
Returns:
True if the dimension was updated successfully, False otherwise
```python
dim = obj.dimensions['dimension_id']
dim.update(definition = 'Customer', label = 'Customer_dimension')
app.save()
```
#### ObjectDimension.delete()
Deletes the dimension from the Qlik Sense Server
Returns:
True if the dimension was deleted successfully, False otherwise
```python
dim = app.dimensions['dimension_id']
dim.delete()
app.save()
```
## Roadmap
* support for master objects in the app
* support for hierarchical dimensions
* support for master item tags
* support for adding dimensions and measures to the object
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
# History
## [0.0.24] - 2024-09-28
- Object.copy() function now can copy complex objects such as filterpanes and containers.
## [0.0.23] - 2024-09-15
- Fixed a bug in the sheet.copy function that sometimes caused objects to be duplicated on the target sheet
## [0.0.22] - 2024-09-02
- Minor changes
## [0.0.21] - 2024-09-01
- Added sheet.copy and object.copy functions, now sheets and objects can be easily copied to another apps
- Added measure.copy and dimension.copy functions, makes the syntax clearer
- load function now can be rerun without recreating the app object
- measures.add, dimensions.add and variables.add now return the ID of the object created (None if failed)
- Added sheets.add function, which creates a new sheet in the app
- Added sheet.clear function, which clears all objects from a sheet
## [0.0.20] - 2024-08-26
- Fixed minor bugs
## [0.0.19] - 2024-08-25
- Added bookmark support
- Added support for measure and dimension base colors
- Added 'source' parameter to 'add' function to copy the measure or dimension from another app
- Fixed an error proceeding an empty sheet
- Fixed minor bugs
## [0.0.17] - 2024-01-31
- Fixed some problems that occured if the connection class object was recreated before terminating the connection to Qlik Sense Engine API
## [0.0.16] - 2023-10-03
- Minor changes
## [0.0.15] - 2023-10-03
- Minor changes
## [0.0.14] - 2023-10-01
### Added
- object.export_data() function which performs data export of an object (such as a table or chart) to an xslx or csv file
- get_layout() function for measures, dimensions, variables, sheets and objects; the functions return the json layout
Raw data
{
"_id": null,
"home_page": "https://github.com/ncthuc/qsea",
"name": "qsea",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "QlikSense, Qlik",
"author": "Lev Biriukov",
"author_email": "lbiryukov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cc/b9/56c529c3ede74d610a8ba15b56f73741ce448eb03282b50a0a934354a331/qsea-1.0.0.tar.gz",
"platform": null,
"description": "## Title\r\n\r\nQSEA refers to the Qlik Sense Engine API. \r\n\r\n## Description\r\n\r\nQSEA is designed to automate basic operations with Qlik Sense Enterprise apps in a Pythonic way. With QSEA, you can quickly view and edit variables, master measures, dimensions and sheet charts. For example, you can replace variables in all master measures of your app with just one line of code:\r\n\r\n```python\r\nfor ms in App.measures: ms.update(definition = replace(ms.definition, '$(var1)', '$(var2)'))\r\n```\r\nor quickly move all measures from one app to another:\r\n\r\n```python\r\nfor ms in source_app.measures: ms.copy(target_app)\r\n```\r\nor copy a sheet with all charts from one app to another:\r\n```python\r\nsource_app.sheets['Source_sheet_name'].copy(target_app)\r\n```\r\n\r\n## Installation\r\n\r\n```python\r\npip install qsea\r\n```\r\n\r\n## Table of Contents\r\n- [Getting started](#getting-started)\r\n- [Full Guide](#full-guide)\r\n - [App class](#app-class)\r\n - [App.load()](#appload)\r\n - [App.save()](#appsave)\r\n - [App.reload_data()](#appreload_data)\r\n - [App.children](#appchildren)\r\n - [AppChildren class](#appchildren-class)\r\n - [AppChildren add](#appchildrenadd)\r\n - [Variable class](#variable-class)\r\n - [Variable properties](#variable-properties)\r\n - [Variable.update()](#variableupdate)\r\n - [Variable.delete()](#variabledelete)\r\n - [Variable.rename()](#variablerename)\r\n - [Variable.get_layout()](#variableget_layout)\r\n - [Measure class](#measure-class)\r\n - [Measure properties](#measure-properties)\r\n - [Measure.copy()](#measurecopy)\r\n - [Measure.update()](#measureupdate)\r\n - [Measure.delete()](#measuredelete)\r\n - [Measure.rename()](#measurerename)\r\n - [Measure.get_layout()](#measureget_layout)\r\n - [Measure.get_properties()](#measureget_properties)\r\n - [Dimension class](#dimension-class)\r\n - [Dimension properties](#dimension-properties)\r\n - [Dimension.copy()](#dimensioncopy)\r\n - [Dimension.update()](#dimensionupdate)\r\n - [Dimension.delete()](#dimensiondelete)\r\n - [Dimension.rename()](#dimensionrename)\r\n - [Dimension.get_layout()](#dimensionget_layout)\r\n - [Sheet class](#sheet-class)\r\n - [Sheet properties](#sheet-properties)\r\n - [Sheet.copy()](#sheetcopy)\r\n - [Sheet.load()](#sheetload)\r\n - [Sheet.clear()](#sheetclear)\r\n - [Sheet.get_layout()](#sheetget_layout)\r\n - [Field class](#field-class)\r\n - [Field properties](#field-properties)\r\n - [Bookmark class](#bookmark-class)\r\n - [Bookmark properties](#bookmark-properties)\r\n - [Object class](#object-class)\r\n - [Object properties](#object-properties)\r\n - [Object.export_data()](#objectexport_data)\r\n - [Object.copy()](#objectcopy)\r\n - [Object.load()](#objectload)\r\n - [Object.get_layout()](#objectget_layout)\r\n - [ObjectChildren class](#objectchildren-class)\r\n - [ObjectMeasure class](#objectmeasure-class)\r\n - [ObjectMeasure properties](#objectmeasure-properties)\r\n - [ObjectMeasure.update()](#objectmeasureupdate)\r\n - [ObjectMeasure.delete()](#objectmeasuredelete)\r\n - [ObjectDImension class](#objectdimension-class)\r\n - [ObjectDimension properties](#objectdimension-properties)\r\n - [ObjectDimension.update()](#objectdimensionupdate)\r\n - [ObjectDimension.delete()](#objectdimensiondelete)\r\n- [Roadmap](#roadmap)\r\n- [License](#license)\r\n\r\n## Getting started\r\n\r\nQSEA uses the Qlik Sense Engine API via the Qlik Sense Proxy Service as its main tool, so you'll need a Virtual Proxy and a JWT key to start working with QSEA. Please refer to the following links for help.\r\n\r\nHow to set up JWT authentication\r\nhttps://community.qlik.com/t5/Official-Support-Articles/Qlik-Sense-How-to-set-up-JWT-authentication/ta-p/1716226\r\n\r\nSetting up a Virtual Proxy\r\nhttps://help.qlik.com/en-US/sense-admin/February2024/Subsystems/DeployAdministerQSE/Content/Sense_DeployAdminister/QSEoW/Administer_QSEoW/Managing_QSEoW/create-virtual-proxy.htm\r\n\r\n\r\nYour credentials should look something like this\r\n```python\r\nheader_user = {'Authorization': 'Bearer <Very long API KEY>'}\r\nqlik_url = \"wss://server.domain.com[/virtual proxy]/app/\"\r\n```\r\n\r\nNow we can connect to the Qlik Server:\r\n```python\r\nconn = qsea.Connection(header_user, qlik_url)\r\n```\r\n\r\nLet's create an App object, which represents the application in Qlik Sense.\r\n```python\r\napp = qsea.App(conn, 'MyAppName')\r\n```\r\n\r\nBy default the App class object is almost empty. Use the `load()` function to make use of it:\r\n```python\r\napp.load()\r\n```\r\n\r\nNow all variables, master measures, and dimensions are uploaded to our App object. We can access them by their name:\r\n```python\r\nvar = app.variables['MyVar']\r\nvar.definition\r\n```\r\n\r\n```python\r\nms = app.measures['MyMeasure']\r\nms.label_expression\r\n```\r\n\r\nOr, we can overview their properties via a pandas DataFrame.\r\n```python\r\napp.dimensions.df\r\n```\r\n\r\nLet's create a new measure:\r\n```python\r\napp.measures.add(name = 'MyMeasure', definition = 'sum(Sales)')\r\n```\r\n\r\nor update a variable:\r\n```python\r\nvar.update(definition = 'sum(Sales)')\r\n```\r\n\r\nSave the app to ensure that the changes are reflected in the real Qlik Sense application.\r\n```python\r\napp.save()\r\n```\r\n\r\nLet's copy the set of master dimensions into a new app:\r\n```python\r\nsource_app = qsea.App(conn, 'Source AppName')\r\ntarget_app = qsea.App(conn, 'Target AppName')\r\nsource_app.dimensions.load()\r\ntarget_app.dimensions.load()\r\n\r\nfor dim in source_app.dimensions:\r\n if dim.name not in [target_dim.name for target_dim in target_app.dimensions]: \r\n dim.copy(target_app = target_app)\r\n\r\ntarget_app.save()\r\n```\r\n\r\nBesides master measures, master dimensions, and variables, tables and charts in the App can also be uploaded.\r\n```python\r\napp.load()\r\nsh = app.sheets['MySheet']\r\nsh.load()\r\nfor obj in sh.objects:\r\n obj.load()\r\n for ms on obj.measures:\r\n print(ms.definition)\r\n```\r\n\r\nObjects and entire sheets can be copied to another app. While it is possible to copy sheets via the Qlik Sense interface, in some cases this can cause problems if the set of the master measures/dimensions in the source and target apps are different. Qsea allows to choose whether to match master measure IDs or names.\r\n```python\r\nsource_app = qsea.App(conn, 'Source AppName')\r\ntarget_app = qsea.App(conn, 'Target AppName')\r\nsource_app.load()\r\ntarget_app.load()\r\n\r\nsource_sh = source_app.sheets['SheetToCopy']\r\nsource_sh.copy(target_app = target_app)\r\n\r\nsource_obj = source_app.sheets['SheetWithObject'].objects['SourceObjectID']\r\nsource_obj.copy(target_app = target_app, target_sheet = target_app.sheets['TargetSheet'])\r\n\r\ntarget_app.save()\r\n```\r\n\r\nFor unknown reasons, on certain instances of Qlik Sense, changes in the App may not be visible in the Qlik Sense interface. The usual workaround is to make a new copy of the Application (via QMC or Hub). Usually, all changes can be seen in the copy.\r\n\r\nNote that as it stands, only basic properties, such as names, definitions, and a couple of others, can be accessed via the qsea module.\r\n\r\nMost read-only operations (such as loading apps) can be performed on published apps. However, it is recommended to modify objects only in unpublished apps.\r\n\r\nIt's highly recommended to make a backup copy of your application.\r\n\r\nGood luck!\r\n\r\n## Full Guide\r\n\r\n### Connection class\r\nThe class that represents a dictionary of websocket connections to Qlik Sense Engine API\r\nSince one websocket connection can be used only for one app, this class is used to handle all websocket connections\r\nNew websocket connections are created automatically when a new app object is created\r\n\r\nNote that the Qlik Sense Engine API has a limit of active parallel connections. Since there is no way to terminate the existing connection (except restarting the proxy server that is generally unacceptable), one have to wait for the Qlik Sense Engine to terminate some of the old sessions.\r\nThere is no way to reconnect to an existing connection if the Connection class object is recreated. Thus, it is highly recommended to avoid recreating the Connection class object in order to avoid reaching the limit of active connections.\r\n\r\n### App class\r\nThe class, representing the Qlik Sense application. This is the main object to work with. The class is empty when created; run the `load()` function to make use of it.\r\n\r\n#### App.load()\r\nLoads data from the Qlik Sense application into an App object.\r\n\r\nArgs:\r\n* depth (int): depth of loading\r\n - 1 - app + variables, measures, sheets, fields, dimensions (default value)\r\n - 2 - everything from 1 + sheet objects (tables, sharts etc.)\r\n - 3 - everything from 2 + object dimensions and measures\r\n\r\nDifferent levels can be useful when working with large apps, as a full load can be time-consuming. Only dimensions and measures from standard Qlik Sense charts are uploaded. Uploading dimensions from filter panes is currently not supported.\r\n\r\n```python\r\nApp.load(level = 3)\r\n```\r\n\r\n#### App.save()\r\nYou have to save the App object for the changes to be reflected in the Qlik Sense Application. Note that it is recommended to modify objects only in unpublished apps.\r\n```python\r\nApp.save()\r\n```\r\n\r\n#### App.reload_data()\r\nStarts the script of reloading data into the Qlik Sense Application.\r\n```python\r\nApp.reload_data()\r\n```\r\n\r\n#### App.children\r\napp.load(level = 1) creates several objects of AppChildren class\r\n\r\n### AppChildren class\r\nThe class contains collections of master objects in the Qlik Sense Application:\r\n* `app.variables`: a collection of Variable class objects, representing the variables of the Qlik Sense application\r\n* `app.measures`: a collection of Measure class objects, representing the master measures of the Qlik Sense application\r\n* `app.dimensions`: a collection of Dimension class objects, representing the master dimensions of the Qlik Sense application\r\n* `app.sheets`: a collection of Sheet class objects, representing the sheets of the Qlik Sense application \r\n* `app.fields`: a collection of Field class objects, representing the fields of the Qlik Sense application\r\n\r\nYou can access the main information about each group of objects in a pandas DataFrame via the `.df` attribute:\r\n```python \r\napp.variables.df\r\napp.measures.df\r\n``` \r\n#### AppChildren.add()\r\nUse the `add()` function to add new variables, master measures, master dimensions or sheets to the app. \r\n\r\nArgs:\r\n* name (str): Name of the object to be created.\r\n* definition (str): Definition of the object to be created.\r\n* description (str, optional): Description of the object to be created. Defaults to ''.\r\n* label (str, optional): Label of the object to be created. Defaults to ''.\r\n* label_expression (str, optional): Label expression of the object to be created. Defaults to ''.\r\n* format_type (str, optional): Format type of the object to be created. Defaults to 'U'.\r\n - 'U' for auto\r\n - 'F' for number\r\n - 'M' for money\r\n - 'D' for date\r\n - 'IV' for duration\r\n - 'R' for other\r\n* format_ndec (int, optional): Number of decimals of the object to be created. Defaults to 10.\r\n* format_use_thou (int, optional): Use thousands separator for the object to be created. Defaults to 0.\r\n* format_dec (str, optional): Decimal separator for the object to be created. Defaults to ','.\r\n* format_thou (str, optional): Thousands separator for the object to be created. Defaults to ''.\r\n* base_color (str, optional): Base color (hex) for the object to be created. Defaults to None.\r\n* source (variable, measure or dimension, optional): Source object for the object to be created. Defaults to None.\r\n\r\nReturns: ID of the object created, if created successfully, None otherwise.\r\nOnly parameters applicable to the specific class will be used\r\n```python\r\napp.variables.add(name = 'MyVar', definition = 'sum(Sales)')\r\napp.measures.add(name = 'MyFunc', definition = 'sum(Sales)', format_type = 'F')\r\napp.dimensions.add(name = 'MyDim', definition = 'Customer')\r\napp.measures.add(source = App1.measures['MyFunc'])\r\napp.sheets.add(name = 'MySheet')\r\n```\r\n\r\n### Variable class\r\nThe class represents variables of the application and is a member of the App.variables collection. You can access a specific variable by its name or iterate through them:\r\n```python\r\nvar = app.variables['MyVar']\r\nprint(var.definition)\r\n\r\nfor var in app.variables:\r\n if var.definition == 'sum(Sales)': var.update(name = 'varSales')\r\n```\r\n#### Variable properties\r\n* name: this is the name of the variable you generally use in the Qlik Sense interface\r\n* definition: the formula behind the variable\r\n* description: the description of the variable\r\n* auxiliary\r\n - handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the variable via the `query()` function\r\n - app_handle: the handle of the parent App object\r\n - id: Qlik Sense internal id of the variable\r\n - parent: App-children object; you can access the App class object like this `var.parent.parent`\r\n - created_date: creation date of the variable, as stored in Qlik Sense\r\n - modified_date: date of the last modification of the variable, as stored in Qlik Sense\r\n - script_created: True if the variable is created via the application load script, False if not.\r\n\r\n#### Variable.update()\r\nUpdates the variable on the Qlik Sense Server\r\n\r\nArgs:\r\n* definition (str, optional): new definition of the variable (leave `None` to keep the old value)\r\n* description (str, optional): new description of the variable (leave `None` to keep the old value)\r\n\r\nReturns:\r\n True if the variable was updated successfully, False otherwise\r\n```python\r\nvar = app.variables['MyVar']\r\nvar.update(definition = 'sum(Sales)')\r\napp.save()\r\n```\r\n\r\n#### Variable.delete()\r\nDeletes the variable from the Qlik Sense Server\r\n\r\nReturns:\r\n True if the variable was deleted successfully, False otherwise\r\n\r\n```python\r\nvar = app.variables['MyVar']\r\nvar.delete()\r\napp.save()\r\n```\r\n\r\n#### Variable.rename()\r\nRenames the variable on the Qlik Sense Server. Since there is no direct method to rename the variable, it essentially deletes the variable with the old name, and creates a new one, with the new name.\r\n\r\nReturns:\r\n True if the variable is renamed successfully, False otherwise\r\n\r\n```python\r\nvar = app.variables['MyVar']\r\nvar.rename('MyVarNewName')\r\napp.save()\r\n```\r\n\r\n#### Variable.get_layout()\r\nReturns the json layout of the variable; a shortcut to the GetLayout method of the Engine API\r\n\r\n```python\r\nvar.get_layout()\r\n```\r\n\r\n### Measure class\r\nThe class represents master measures of the application and is a member of the App.measures collection. You can access a specific measure by its name or iterate through them.\r\n```python\r\nms = app.measures['MyMeasure']\r\nprint(ms.definition)\r\n\r\nfor ms in app.measures:\r\n if ms.definition == 'sum(Sales)': ms.update(name = 'Sales')\r\n```\r\n#### Measure properties\r\n* name: the name of the measure you generally use in the Qlik Sense interface\r\n* definition: the formula behind the measure\r\n* description: the description of the measure\r\n* label: the label of the measure, as it appears in charts\r\n* label_expression: the label expression of the measure\r\n* format_type: Format type of the object\r\n - 'U' for auto\r\n - 'F' for number\r\n - 'M' for money\r\n - 'D' for date\r\n - 'IV' for duration\r\n - 'R' for other\r\n* format_ndec: Number of decimals for the object\r\n* format_use_thou: Use thousands separator for the object\r\n* format_dec: Decimal separator for the object\r\n* format_thou: Thousands separator for the object\r\n* base_color: Base color (hex) of the object\r\n* auxiliary\r\n - handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the measure via the `query()` function\r\n - app_handle: the handle of the parent App object\r\n - id: Qlik Sense internal id of the measure\r\n - parent: AppChildren object; you can access the App class object like this `ms.parent.parent`\r\n - created_date: creation date of the measure, as stored in Qlik Sense\r\n - modified_date: date of the last modification of the measure, as stored in Qlik Sense\r\n\r\n#### Measure.copy()\r\nCreates a copy of the master measure in another app\r\n\r\nArgs: target_app (App): The target app, where the measure will be copied\r\nReturns: str: ID of the measure created if successful, None otherwise\r\n\r\n#### Measure.update()\r\nUpdates the measure on the Qlik Sense Server\r\n\r\nArgs: \r\n* definition (str, optional): The definition of the measure\r\n* description (str, optional): the description of the measure\r\n* label (str, optional): the label of the measure, as it appears in charts\r\n* label_expression (str, optional): the label expression of the measure\r\n* format_type (str, optional): Format type of the object to be created. Defaults to 'U'.\r\n - 'U' for auto\r\n - 'F' for number\r\n - 'M' for money\r\n - 'D' for date\r\n - 'IV' for duration\r\n - 'R' for other\r\n* format_ndec (int, optional): Number of decimals for the object to be created. Defaults to 10.\r\n* format_use_thou (int, optional): Use thousands separator for the object to be created. Defaults to 0.\r\n* format_dec (str, optional): Decimal separator for the object to be created. Defaults to ','.\r\n* format_thou (str, optional): Thousands separator for the object to be created. Defaults to ''.\r\n* base_color (str, optional): Base color (hex) of the object to be created. Defaults to None.\r\n\r\nReturns: \r\n True if the measure was updated successfully, False otherwise\r\n\r\n```python\r\nms = app.measures['MyMeasure']\r\nms.update(definition = 'sum(Sales)', label = 'Total Sales', format_type = 'F')\r\napp.save()\r\n```\r\n\r\n#### Measure.delete()\r\nDeletes the measure from the Qlik Sense Server\r\n\r\nReturns:\r\n True if the measure was deleted successfully, False otherwise\r\n\r\n```python\r\nms = app.measures['MyMeasure']\r\nms.delete()\r\napp.save()\r\n```\r\n\r\n#### Measure.rename()\r\nRenames the measure on the Qlik Sense Server.\r\n\r\nReturns:\r\n True if the measure was renamed successfully, False otherwise\r\n\r\n```python\r\nms = app.measures['MyMeasure']\r\nms.rename('MyMeasureNewName')\r\napp.save()\r\n```\r\n\r\n#### Measure.get_layout()\r\nReturns the json layout of the measure; a shortcut to the GetLayout method of the Engine API\r\n\r\n```python\r\nms.get_layout()\r\n```\r\n\r\n#### Measure.get_properties()\r\nReturns the json properties of the measure; a shortcut to the GetProperties method of the Engine API\r\n\r\n```python\r\nms.get_properties()\r\n```\r\n\r\n### Dimension class\r\nThe class represents master dimensions of the application and is a member of the App.dimensions collection. You can access a specific dimension by its name or iterate through them. Note that hierarchical dimensions are not yet supported.\"\r\n\r\n```python\r\ndim = app.dimensions['MyDimension']\r\nprint(dim.definition)\r\n\r\nfor dim in app.dimensions:\r\n if dim.definition == '[Customer]': dim.update(name = 'Customer_dimension')\r\n```\r\n\r\n#### Dimension properties\r\n* name: the name of the dimension you generally use in the Qlik Sense interface\r\n* definition: the formula behind the dimension\r\n* label: the label of the dimension, as it appears in charts\r\n* base_color: Base color (hex) of the object\r\n* auxiliary\r\n - handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the dimension via the `query()` function\r\n - app_handle: the handle of the parent App object\r\n - id: Qlik Sense internal id of the dimension\r\n - parent: AppChildren object; you can access the App class object like this `dim.parent.parent`\r\n - created_date: creation date of the dimension, as stored in Qlik Sense\r\n - modified_date: date of the last modification of the dimension, as stored in Qlik Sense\r\n\r\n#### Dimension.copy()\r\nCreates a copy of the master dimension in another app\r\n\r\nArgs: target_app (App): The target app, where the dimension will be copied\r\nReturns: str: ID of the dimension created if successful, None otherwise\r\n\r\n#### Dimension.update()\r\nUpdates the dimension on the Qlik Sense Server\r\n\r\nArgs: \r\n* definition (str, optional): The definition of the dimension\r\n* label (str, optional): the label of the dimension, as it appears in charts\r\n* base_color (str, optional): Base color (hex) of the object to be created. Defaults to None.\r\n\r\nReturns: \r\n True if the dimension was updated successfully, False otherwise\r\n\r\n```python\r\ndim = app.dimensions['MyDimension']\r\ndim.update(definition = 'Customer', label = 'Customer_dimension')\r\napp.save()\r\n```\r\n\r\n#### Dimension.delete()\r\nDeletes the dimension from the Qlik Sense Server\r\n\r\nReturns:\r\n True if the dimension was deleted successfully, False otherwise\r\n\r\n```python\r\ndim = app.dimensions['MyDimension']\r\ndim.delete()\r\napp.save()\r\n```\r\n\r\n#### Dimension.rename()\r\nRenames the dimension on the Qlik Sense Server.\r\n\r\nReturns:\r\n True if the dimension was renamed succesfully, False otherwise\r\n\r\n```python\r\ndim = app.dimensions['MyDimension']\r\ndim.rename('MyDimensionNewName')\r\napp.save()\r\n```\r\n\r\n#### Dimension.get_layout()\r\nReturns the json layout of the dimension; a shortcut to the GetLayout method of the Engine API\r\n\r\n```python\r\ndim.get_layout()\r\n```\r\n\r\n### Sheet class\r\nThe class represents the sheets of the application and is a member of the App.sheets collection. You can access objects on the sheets, such as charts and tables, via the Sheet class object.\r\n\r\n```python\r\nfor sh in app.sheets:\r\n print(sh.name)\r\n```\r\n\r\n#### Sheet properties\r\n* name: that's the name of the sheet\r\n* description: the description of the sheet\r\n* auxiliary\r\n - handle: the internal handle of the object in Qlik Sense Engine API; can be used to access the sheet via the `query()` function\r\n - app_handle: the handle of the parent App object\r\n - id: Qlik Sense internal id of the sheet\r\n - parent: AppChildren object; you can access the App class object like this `ms.parent.parent`\r\n - created_date: creation date of the sheet, as stored in Qlik Sense\r\n - modified_date: date of the last modification of the sheet, as stored in Qlik Sense\r\n - published: True if the sheet is published, False if not\r\n - approved: True if the sheet is approved, False if not\r\n - owner_id: GUID of the owner of the sheet\r\n - owner_name: name of the owner of the sheet\r\n\r\n#### Sheet.copy()\r\nCreates a copy of the sheet in another app\r\n\r\nArgs: \r\n* target_app (App): The target app, where the sheet will be copied\r\n* master_match (str): 'name' by default: master measures and dimensions in the new object are matched by name. If 'id', they are matched by id.\r\nReturns: str: ID of the sheet created if successful, None otherwise\r\n\r\n```python\r\nsource_app = qsea.App(conn, 'Source AppName')\r\ntarget_app = qsea.App(conn, 'Target AppName')\r\nsource_app.load()\r\ntarget_app.load()\r\n\r\nsource_sh = source_app.sheets['SheetToCopy']\r\nsource_sh.copy(target_app = target_app)\r\n```\r\n\r\nNote: Some objects, not accessible via API (such as buttons) are not copied. Copying of conatainers and filterpanes is not supported. Master objects can be copied correctly only if they have 1-1 correspondence between the source and target apps and have the same IDs. It can be used as a workaround for the filterpane copy problem in some cases.\r\n\r\n#### Sheet.load()\r\nLoads objects from the sheet in a Qlik Sense application into a Sheet class object\r\n\r\n```python\r\nsh = App.sheets['MySheet']\r\nsh.load()\r\n\r\nfor obj in sh.objects:\r\n print(obj.type)\r\n```\r\n\r\n#### Sheet.clear()\r\nClears all objects from the sheet in a Qlik Sense application\r\n\r\n#### Sheet.get_layout()\r\nReturns the json layout of the sheet; a shortcut to the GetLayout method of the Engine API\r\n\r\n```python\r\nsh.get_layout()\r\n```\r\n\r\n\r\n### Field class\r\nThe class represents the fields of the application and is a member of the App.fields collection. You can only use the class for information purposes; no changes can be made with fields via QSEA.\r\n\r\n```python\r\nfor fld in app.fields:\r\n print(field.table_name, field.name)\r\n```\r\n\r\n#### Field properties\r\n* name: name of the field, as it appears in the model\r\n* table_name: name of the table, containing the field\r\n* information_density, non_nulls, rows_count, subset_ratio, distinct_values_count, present_distinct_values, key_type, tags: properties of the fields as they can be found in the data model\r\n* auxiliary\r\n - handle: internal handle of the field object\r\n - app_handle: handle of the parent App object\r\n\r\n### Bookmark class\r\nThe class represents the bookmarks of the application and is a member of the App.bookmarks collection. You can only use the class for information purposes; no changes can be made with bookmarks via QSEA.\r\n\r\n```python\r\nfor bm in app.bookmarks:\r\n print(bm.name)\r\n```\r\n\r\n#### Bookmark properties\r\n* name: name of the bookmark\r\n* owner_id: GUID of the owner of the bookmark\r\n* owner_user_id: user id of the owner of the bookmark\r\n* owner_name: name of the owner of the bookmark\r\n* description: description of the bookmark\r\n* state_data: selection properties of the bookmark in JSON format; unfortionately, the whole list of selections can not be retrieved correctly\r\n* auxiliary\r\n - handle: internal handle of the bookmark object\r\n - app_handle: handle of the parent App object\r\n - id: Qlik Sense internal id of the bookmark\r\n - parent: AppChildren object; you can access the App class object like this `ms.parent.parent`\r\n - created_date: creation date of the bookmark, as stored in Qlik Sense\r\n - modified_date: date of the last modification of the bookmark, as stored in Qlik Sense\r\n - published: True if the bookmark is published, False if not\r\n - approved: True if the bookmark is approved, False if not\r\n\r\n\r\n\r\n\r\n### Object class \r\nThe class represents the objects on the sheet, such as charts and tables, and is a member of the SheetChildren collection.\r\n\r\n#### Object properties\r\n* type: type of the object, such as 'piechart' or 'pivot-table'\r\n* col, row, colspan, rowspan, bounds_y, bounds_x, bounds_width, bounds_height: parameters referring to the location of an object on the sheet\r\n* auxiliary\r\n - handle: the internal handle of the object in the Qlik Sense Engine API; can be used to access the object via the `query()` function\r\n - sheet_handle: handle of the parent sheet\r\n - sheet: the Sheet object, on which the object itself is located\r\n - id: Qlik Sense internal id of the object\r\n - parent: SheetChildren object\r\n\r\n#### Object.export_data()\r\nPerforms data export of an object (such as a table or chart) to an xslx or csv file.\r\n\r\nArgs: \r\n* file_type (str, optional): 'xlsx' or 'csv', 'xlsx' by default\r\n \r\nReturns: the path to the downloaded file in case of success, None if failed\r\n\r\n#### Object.copy()\r\nCreates a copy of the object in the specified sheet of another app\r\n\r\nArgs: \r\n* target_app (App): The target app, where the sheet will be copied\r\n* target_sheet (Sheet): The target sheet, where the object will be copied\r\n* col (int, optional): The column number of the new object, None by default (the column of the source object is used)\r\n* row (int, optional): The row number of the new object, None by default (the row of the source object is used)\r\n* colspan (int, optional): The number of columns occupied by the new object, None by default (the colspan of the source object is used)\r\n* rowspan (int, optional): The number of rows occupied by the new object, None by default (the rowspan of the source object is used)\r\n* master_match (str): 'name' by default: master measures and dimensions in the new object are matched by name. If 'id', they are matched by id.\r\nReturns: str: ID of the sheet created if successful, None otherwise\r\n\r\n```python\r\nsource_object.copy(target_app, target_sheet)\r\n```\r\n\r\n#### Object.load()\r\nLoads measures and dimensions of the object in a Qlik Sense application into an Object class instance.\r\n\r\n```python\r\nsh = App.sheets['MySheet']\r\nsh.load()\r\n\r\nfor obj in sh.objects:\r\n if obj.type == 'piechart': \r\n obj.load()\r\n print(obj.dimensions.count)\r\n```\r\n\r\n#### Object.get_layout()\r\nReturns the json layout of the object; a shortcut to the GetLayout method of the Engine API\r\n\r\n```python\r\nobj.get_layout()\r\n```\r\n\r\n### ObjectChildren class\r\nThe class contains collections of measures and dimensions in the object on the sheet:\r\n* `object.measures`: a collection of ObjectMeasure class objects, representing the measures in the object on the sheet\r\n* `object.dimensions`: a collection of ObjectDimension class objects, representing the dimensions in the object on the sheet\r\n* `object.subitems`: a collection of Object class objects, representing the subitems of filterpane and container type objects\r\n\r\nYou can access the main information in pandas DataFrame via `.df`:\r\n```python\r\nApp.sheets['MySheet'].objects['object_id'].measures.df\r\n```\r\n\r\nAdding measures and dimensions to app objects is not supported yet.\r\n\r\n\r\n### ObjectMeasure class\r\nThis class represents measures of the object on the sheet and is a member of the object.measures collection. Since there may be no specific name for the measure in the object, the internal Qlik ID is used instead of the name. Thus, you can either iterate through measures or call them by the internal Qlik ID:\r\n```python\r\nms = obj.measures['measure_id']\r\nprint(ms.definition)\r\n\r\nfor ms in obj.measures:\r\n if ms.definition == 'sum(Sales)': ms.update(definition = 'sum(Incomes)')\r\n```\r\n\r\n#### ObjectMeasure properties\r\n* name: internal Qlik id of the measure\r\n* definition: the formula behind the measure\r\n* label: the label of the measure, as it appears in the charts\r\n* label_expression: the label expression of the measure\r\n* calc_condition: calculation condition for the measure\r\n* library_id: if a master measure is used, this refers to its ID\r\n* format_type: Format type of the object\r\n - 'U' for auto\r\n - 'F' for number\r\n - 'M' for money\r\n - 'D' for date\r\n - 'IV' for duration\r\n - 'R' for other\r\n* format_ndec: Number of decimals of the object\r\n* format_use_thou: Use thousands separator for the object\r\n* format_dec: Decimal separator for the object\r\n* format_thou: Thousands separator for the object\r\n* auxiliary\r\n - app_handle: the handle of the parent App object\r\n - parent: ObjectChildren object\r\n - object: you can access the Object class object like this `ms.object`\r\n \r\n\r\n#### ObjectMeasure.update()\r\nUpdates the measure in the object on the sheet.\r\n\r\nArgs: \r\n* definition (str, optional): The definition of the measure\r\n* label (str, optional): the new label of the measure, as it appears in charts\r\n* label_expression (str, optional): the label expression of the measure\r\n* calc_condition (str, optional): calculation condition for the measure\r\n* library_id (str, optional): id of the master measure\r\n* format_type (str, optional): Format type of the object. Defaults to 'U'.\r\n - 'U' for auto\r\n - 'F' for number\r\n - 'M' for money\r\n - 'D' for date\r\n - 'IV' for duration\r\n - 'R' for other\r\n* format_use_thou (int, optional): Use thousands separator for the object. Defaults to 0.\r\n* format_dec (str, optional): Decimal separator for the object. Defaults to ','.\r\n* format_thou (str, optional): Thousands separator for the object. Defaults to ''.\r\n\r\nReturns: \r\n True if the measure was updated successfully, False otherwise\r\n\r\n```python\r\nms = obj.measures['measure_id']\r\nms.update(definition = 'sum(Sales)', label = 'Total Sales', format_type = 'F')\r\napp.save()\r\n```\r\n\r\n#### ObjectMeasure.delete()\r\nDeletes the measure from the object on the sheet\r\n\r\nReturns:\r\n True if the measure was deleted successfully, False otherwise\r\n\r\n```python\r\nms = obj.measures['measure_id']\r\nms.delete()\r\napp.save()\r\n```\r\n\r\n### ObjectDimension class\r\nThis class represents dimensions of the object on the sheet and is a member of the object.dimensions collection. Since there may be no specific name for the dimension in the object, the internal Qlik ID is used instead of the name. Thus, you can either iterate through dimensions or call them by the internal Qlik ID:\r\n```python\r\ndim = obj.measures['dimension_id']\r\nprint(dim.definition)\r\n\r\nfor dim in obj.dimensions:\r\n if dim.definition == '[Customer]': dim.update(definition = '[Supplier]')\r\n```\r\n\r\nNote that hierarchical dimensions are not supported yet.\r\n\r\n#### ObjectDimension properties\r\n* name: internal Qlik id of the dimension\r\n* definition: the formula behind the dimension\r\n* label: the label of the dimension, as it appears in the charts\r\n* auxiliary\r\n - app_handle: the handle of the parent App object\r\n - parent: ObjectChildren object\r\n - object: you can access the Object class object like this `dim.object`\r\n\r\n#### ObjectDimension.update()\r\nUpdates the dimension in the object on the sheet\r\n\r\nArgs: \r\n* definition (str, optional): the definition of the dimension\r\n* label (str, optional): the label of the dimension, as it appears in charts\r\n* calc_condition (str, optional): calculation condition for the dimension\r\n\r\nReturns: \r\n True if the dimension was updated successfully, False otherwise\r\n\r\n```python\r\ndim = obj.dimensions['dimension_id']\r\ndim.update(definition = 'Customer', label = 'Customer_dimension')\r\napp.save()\r\n```\r\n\r\n#### ObjectDimension.delete()\r\nDeletes the dimension from the Qlik Sense Server\r\n\r\nReturns:\r\n True if the dimension was deleted successfully, False otherwise\r\n\r\n```python\r\ndim = app.dimensions['dimension_id']\r\ndim.delete()\r\napp.save()\r\n```\r\n\r\n## Roadmap\r\n* support for master objects in the app\r\n* support for hierarchical dimensions\r\n* support for master item tags\r\n* support for adding dimensions and measures to the object\r\n\r\n\r\n## License\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n\r\n# History\r\n\r\n## [0.0.24] - 2024-09-28\r\n- Object.copy() function now can copy complex objects such as filterpanes and containers.\r\n\r\n## [0.0.23] - 2024-09-15\r\n- Fixed a bug in the sheet.copy function that sometimes caused objects to be duplicated on the target sheet\r\n\r\n## [0.0.22] - 2024-09-02\r\n- Minor changes\r\n\r\n## [0.0.21] - 2024-09-01\r\n- Added sheet.copy and object.copy functions, now sheets and objects can be easily copied to another apps\r\n- Added measure.copy and dimension.copy functions, makes the syntax clearer\r\n- load function now can be rerun without recreating the app object\r\n- measures.add, dimensions.add and variables.add now return the ID of the object created (None if failed)\r\n- Added sheets.add function, which creates a new sheet in the app\r\n- Added sheet.clear function, which clears all objects from a sheet\r\n\r\n## [0.0.20] - 2024-08-26\r\n- Fixed minor bugs\r\n\r\n## [0.0.19] - 2024-08-25\r\n- Added bookmark support\r\n- Added support for measure and dimension base colors\r\n- Added 'source' parameter to 'add' function to copy the measure or dimension from another app \r\n- Fixed an error proceeding an empty sheet\r\n- Fixed minor bugs\r\n\r\n## [0.0.17] - 2024-01-31\r\n- Fixed some problems that occured if the connection class object was recreated before terminating the connection to Qlik Sense Engine API\r\n\r\n## [0.0.16] - 2023-10-03\r\n- Minor changes\r\n\r\n## [0.0.15] - 2023-10-03\r\n- Minor changes\r\n\r\n## [0.0.14] - 2023-10-01\r\n\r\n### Added\r\n- object.export_data() function which performs data export of an object (such as a table or chart) to an xslx or csv file\r\n- get_layout() function for measures, dimensions, variables, sheets and objects; the functions return the json layout\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convenient way to work with Qlik Sense Engine API from Python",
"version": "1.0.0",
"project_urls": {
"Download": "https://pypi.org/project/qsea/",
"Homepage": "https://github.com/ncthuc/qsea"
},
"split_keywords": [
"qliksense",
" qlik"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a34091c935c9d09d6349595c2da389bf187e5e6fe3d4d1fa9b3d2fe7300ded56",
"md5": "a7cc818f782e948a48b5ad4cf39a465f",
"sha256": "f314f052c8b6bee653b398f360f402abe2f9686718a32f6de20cf7b9e70e61ed"
},
"downloads": -1,
"filename": "qsea-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7cc818f782e948a48b5ad4cf39a465f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64125,
"upload_time": "2024-09-28T20:32:22",
"upload_time_iso_8601": "2024-09-28T20:32:22.707806Z",
"url": "https://files.pythonhosted.org/packages/a3/40/91c935c9d09d6349595c2da389bf187e5e6fe3d4d1fa9b3d2fe7300ded56/qsea-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ccb956c529c3ede74d610a8ba15b56f73741ce448eb03282b50a0a934354a331",
"md5": "6234bb7f278417a7a89545a1745937da",
"sha256": "48aeb75db65799379bee047fcbc305f2f3557b8e1f7331917035db8e984dcd50"
},
"downloads": -1,
"filename": "qsea-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6234bb7f278417a7a89545a1745937da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 47158,
"upload_time": "2024-09-28T20:32:24",
"upload_time_iso_8601": "2024-09-28T20:32:24.933453Z",
"url": "https://files.pythonhosted.org/packages/cc/b9/56c529c3ede74d610a8ba15b56f73741ce448eb03282b50a0a934354a331/qsea-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-28 20:32:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ncthuc",
"github_project": "qsea",
"github_not_found": true,
"lcname": "qsea"
}
JSON
