From 70153f63a262be61905ff2488cf4596c0f0933e5 Mon Sep 17 00:00:00 2001
From: Maximilian Schulz <83698606+maxschulz-COL@users.noreply.github.com>
Date: Thu, 12 Oct 2023 15:11:06 +0200
Subject: [PATCH] General improvements to docs and linters (#107)
---
.github/pull_request_template.md | 4 +-
.pre-commit-config.yaml | 8 ++--
CODE_OF_CONDUCT.md | 12 +++---
pyproject.toml | 5 +++
tools/find_forbidden_words_in_repo.sh | 15 ++++---
tools/forbidden_words.txt | 1 +
vizro-core/CHANGELOG.md | 2 +-
..._144547_maximilian_schulz_general_todos.md | 42 +++++++++++++++++++
vizro-core/docs/pages/development/authors.md | 2 +
.../docs/pages/development/contributing.md | 2 +-
.../docs/pages/explanation/why_vizro.md | 26 ++++++------
vizro-core/docs/pages/user_guides/actions.md | 2 +-
vizro-core/docs/pages/user_guides/assets.md | 4 +-
.../docs/pages/user_guides/dashboard.md | 2 +-
.../docs/pages/user_guides/navigation.md | 2 +-
vizro-core/pyproject.toml | 2 +-
vizro-core/src/vizro/_vizro.py | 2 +-
.../src/vizro/actions/_filter_action.py | 2 +-
.../src/vizro/actions/_on_page_load_action.py | 2 +-
.../src/vizro/actions/_parameter_action.py | 2 +-
.../src/vizro/actions/export_data_action.py | 2 +-
.../actions/filter_interaction_action.py | 2 +-
.../vizro/models/_action/_actions_chain.py | 2 +-
.../models/_components/form/_form_utils.py | 2 +-
.../vizro/models/_navigation/navigation.py | 2 +-
.../tests/unit/vizro/models/test_base.py | 2 +-
26 files changed, 101 insertions(+), 50 deletions(-)
create mode 100644 tools/forbidden_words.txt
create mode 100644 vizro-core/changelog.d/20231011_144547_maximilian_schulz_general_todos.md
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index a3acc7391..8accc9054 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -22,5 +22,5 @@
- [ ] I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":
- I submit this contribution under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt) and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
- - I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorised to submit this contribution on behalf of the original creator(s) or their licensees.
- - I certify that the use of this contribution as authorised by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
+ - I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
+ - I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1c266ab55..4cd228c4b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -17,16 +17,18 @@ repos:
entry: python tools/check_for_datafiles.py
language: python
pass_filenames: false
- - id: check-spelling
- name: check-spelling
+ - id: check-forbidden-words
+ name: check-forbidden-words
entry: tools/find_forbidden_words_in_repo.sh
language: script
pass_filenames: false
- repo: https://github.com/codespell-project/codespell
- rev: v2.2.4
+ rev: v2.2.6
hooks:
- id: codespell
+ additional_dependencies:
+ - tomli
# Linter for json, yaml, md, css and more
- repo: https://github.com/pre-commit/mirrors-prettier
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 1613856d2..d9e095858 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -11,7 +11,7 @@ appearance, race, religion, or sexual identity and orientation.
## Our Standards
-Examples of behaviour that contributes to creating a positive environment
+Examples of behavior that contributes to creating a positive environment
include:
- Using welcoming and inclusive language
@@ -20,7 +20,7 @@ include:
- Focusing on what is best for the community
- Showing empathy towards other community members
-Examples of unacceptable behaviour by participants include:
+Examples of unacceptable behavior by participants include:
- The use of sexualised language or imagery and unwelcome sexual attention or
advances
@@ -34,13 +34,13 @@ Examples of unacceptable behaviour by participants include:
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
-behaviour and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behaviour.
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviours that they deem inappropriate,
+permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
@@ -54,7 +54,7 @@ further defined and clarified by project maintainers.
## Enforcement
-Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
diff --git a/pyproject.toml b/pyproject.toml
index 10cd78566..631dd2324 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,6 +12,11 @@ exclude_dirs = ["tests"]
line-length = 120
target-version = ["py38"]
+[tool.codespell]
+builtin = "clear,rare,en-GB_to_en-US"
+dictionary = "tools/forbidden_words.txt"
+ignore-words-list = "grey"
+
[tool.mypy]
# strict checks : strict = true
check_untyped_defs = true
diff --git a/tools/find_forbidden_words_in_repo.sh b/tools/find_forbidden_words_in_repo.sh
index 1495731bd..2044a0ae7 100755
--- a/tools/find_forbidden_words_in_repo.sh
+++ b/tools/find_forbidden_words_in_repo.sh
@@ -1,13 +1,12 @@
#!/bin/bash
-words=$"colour\|visualisation"
-words_finder=$(grep -Irwno --exclude=find_forbidden_words_in_repo.sh --exclude-dir={.git,*cache*,*node_modules*,venv} . -e "$words")
+# openai.api_base check
+api_base_word="openai.api_base"
+api_base_finder=$(grep -Irwno --exclude=find_forbidden_words_in_repo.sh --exclude-dir={.git,*cache*,*node_modules*,venv} . -e "$api_base_word")
-if [[ $words_finder ]]
-then
- echo "Incorrect spelling for $words:
-$words_finder"
+# If openai.api_base is found
+if [[ $api_base_finder ]]; then
+ echo "Please remove URL base for development:"
+ echo "$api_base_finder"
exit 1
-else
- echo "No $words found in the repo"
fi
diff --git a/tools/forbidden_words.txt b/tools/forbidden_words.txt
new file mode 100644
index 000000000..af5101b91
--- /dev/null
+++ b/tools/forbidden_words.txt
@@ -0,0 +1 @@
+quantumblack->Please do not refer specific entities
diff --git a/vizro-core/CHANGELOG.md b/vizro-core/CHANGELOG.md
index 6b0864333..7634ce663 100644
--- a/vizro-core/CHANGELOG.md
+++ b/vizro-core/CHANGELOG.md
@@ -72,7 +72,7 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
- Optimize the client-server communication ([#34](https://github.com/mckinsey/vizro/pull/34))
- - Eliminate most server side callbacks in favour of client-side callbacks
+ - Eliminate most server side callbacks in favor of client-side callbacks
- Add tests for client-side callbacks written in Node.js framework called `jest`.
- Add hatch command `hatch run test-js` that runs unit tests written in `jest`.
- Logging information now only displayed for action function carried out (no trigger or finished information)
diff --git a/vizro-core/changelog.d/20231011_144547_maximilian_schulz_general_todos.md b/vizro-core/changelog.d/20231011_144547_maximilian_schulz_general_todos.md
new file mode 100644
index 000000000..d57e34cc2
--- /dev/null
+++ b/vizro-core/changelog.d/20231011_144547_maximilian_schulz_general_todos.md
@@ -0,0 +1,42 @@
+
+
+
+
+
+
+
+
diff --git a/vizro-core/docs/pages/development/authors.md b/vizro-core/docs/pages/development/authors.md
index 132016b74..4883b6149 100644
--- a/vizro-core/docs/pages/development/authors.md
+++ b/vizro-core/docs/pages/development/authors.md
@@ -14,6 +14,8 @@
## Previous team members and code contributors
+Natalia Kurakina,
+[Leon Nallamuthu](https://github.com/leonnallamuthu),
[axa99](https://github.com/axa99),
[Jo Stichbury](https://github.com/stichbury),
[Juan Luis Cano Rodríguez](https://github.com/astrojuanlu),
diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md
index 2c74b82f5..89dadbb2f 100644
--- a/vizro-core/docs/pages/development/contributing.md
+++ b/vizro-core/docs/pages/development/contributing.md
@@ -1,6 +1,6 @@
## Contributing guidelines
-Contributions of all experience levels are welcome! There are many ways to contribute, and we appreciate all of them. Please use our [issues page](https://github.com/mckinsey/vizro/issues) to discuss any contributions.
+Contributions of all experience levels are welcome! There are many ways to contribute, and we appreciate all of them. Please use our [issues page](https://github.com/mckinsey/vizro/issues) to discuss any contributions. Before opening a pull request, please ensure you've first opened an issue to discuss the contribution.
### Found a bug
diff --git a/vizro-core/docs/pages/explanation/why_vizro.md b/vizro-core/docs/pages/explanation/why_vizro.md
index 9becbda08..cae35ccf6 100644
--- a/vizro-core/docs/pages/explanation/why_vizro.md
+++ b/vizro-core/docs/pages/explanation/why_vizro.md
@@ -28,19 +28,19 @@ Vizro is intended to support several niches between the benefits provided by tho
However, in general, there are several areas of functionality where Vizro can be particularly useful, e.g., in providing a simple configuration to speed up the assembly of components, leveraging inbuilt visual design, application architecture, and coding standards,
along with the ability to scale easily across multiple developers and implementations:
-| Functionality | Benefits | In context of Python packages | In context of BI tools |
-| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Assembly system** - Configuration-driven assembly system of Vizro automatically builds user-friendly, higher-level dashboard concepts (e.g. a filter) from low-level individual components (e.g. a dropdown component plus a filtering function).
| - Removes the need for users to learn how to write the “glue code” which combines lower-level components.
- Removes the time taken to write, test and optimise the “glue code” which combines lower-level components.
- Reduces what can be 1000s of lines of code down to dozens of lines of configuration.
| Many Python packages still require a moderate understanding of the coding required to assemble higher-level dashboard concepts, which necessitates the creation of “glue code” to combine lower-level components.
Vizro primarily provides a configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly provided by Vizro. |
-| **Inbuilt visual design decisions** - UX decisions such as placement of filters and orientation of charts in relation to other components on the screen.
- Visual design decisions such as chart formatting and spacing between components.
- Colors including text, backgrounds and chart contents.
| - Ensures visual consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on visual design decisions.
- Removes the need for advanced expertise in visual design.
- Ensures basic color accessibility for most likely color combinations.
| Many Python packages provide inbuilt color choices, and visual design choices for certain components.
Vizro applies that to a wide range of component combinations and complex user flows, offering a wholistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customisation and flexibility. | Many BI tools provide inbuilt color choices and visual design choices for certain components.
Vizro provides inbuilt visual design for components in addition to the ability to customise them in a flexible way where needed (for example through CSS), and provides automatic arrangement of components on the screen. |
-| **Inbuilt application architecture decisions** - The architectural decisions required to connect components in advanced ways - such as combining connecting filters to charts with multi-screen navigation to allow drill-throughs between screens.
| - Ensures structural consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on architectural decisions or development.
- Removes need for advanced expertise in application architecture.
| Many Python packages provide inbuilt application architecture choices for certain functionalities.
Vizro applies that to a wide range of component combinations and complex user flows, offering a wholistic and comprehensive approach to the entire application architecture, whilst allowing customisation and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. |
-| **Declarative configuration, in multiple formats** - Configuration is declarative and can be written in Python or a configuration language such as YAML, JSON and TOML.
| - The range of formats enables flexibility in implementations (and can be extended in future).
- Formats such as YAML support programmatic construction of dashboards (for example being dynamically generated from a Kedro pipeline).
- The focus on editing configuration directly, rather than via GUI or drop-and-drag interfaces, allows for ease of collaboration.
| Many Python packages provide a mostly declarative configuration, with limited ability to leverage multiple formats such as Pydantic models and JSON.
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. |
-| **Mostly tech agnostic “grammar of dashboards”** - The configuration follows a “grammar of dashboards” which is mostly generic and tech agnostic (rather than being specific to any Python package or coding language).
| - Enables a more intuitive understanding of how to write the configuration.
- Enables the configuration to apply to other Python packages or other coding languages in future. (NB: this would require an adjustment to the underlying assembly core code).
| Many Python packages provide an effective “grammar of charts” and Python specific declaration.
Vizro provides a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilise an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro provides an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). |
-| **Inbuilt validation** - The ability to leverage Pydantic models automatically provides meaningful feedback to users about configuration choices.
| - Increases ease of use by guiding users, providing early validation and clear feedback throughout the configuration process.
- This validation feedback can also be utilised by processes which construct the configuration programmatically, such as via a Kedro pipeline.
| Many Python packages provide individual components or non-Pydantic based models.
Vizro provides the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and provide feedback to the manual user to help guide through that process.
Vizro utilises a flexible system which can be extended to provide feedback to programmatic generation of configuration. |
-| **Modularity** - The standardisation applied by Vizro (in terms of visual design, application architecture and coding standards) makes it possible to re-use configuration, charts, components and extensions such as custom actions, between implementations.
| - Speeds up development by allowing re-use of existing implementations.
- Facilitates collaboration between users by allowing knowledge to be encoded in modular ways.
| Many Python packages provide modularity of components such as charts and controls.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools provide extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. |
-| **Flexibility** - The ability to utilise the low-code approach of configuration with the high-code approach of custom functions provides flexibility in implementation for both less technical and more technical users.
| - The low-code configuration driven approach enables all users to create fairly flexible dashboards easily.
- The high-code approach of using custom functions in a structured way provides more technical users with flexibility to extend functionality almost infinitely.
| Many Python packages provide some low-code and/or high-code approaches, which offer varying degrees of flexibility.
Vizro provides a wholistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. |
-| **Scaling** - The consistency in visual design, application architecture and code standards, combined with the ease of collaboration between Python developers, allows scaling within and between projects by facilitating re-use, extension and programmatic updates of configurations.
| - Sections of configuration can be re-used and tailored easily, allowing implementations to scale across or between projects.
- New joiners to a team can get up to speed quickly, allowing teams to scale in size.
- Other teams can inherit configurations easily, allowing implementations to scale between teams.
- Updates can be propagated to configurations from a central location, allowing adjustments and updates to scale easily across large implementations.
- Inbuilt visual design decisions provide visual consistency.
- Leveraging collaborative coding mechanisms such as Git enables almost any number of developers to collaborate effectively.
| Many Python packages benefit from the ability to propagate updates programmatically, while applying that to “glue code”.
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. |
-| **Python first** - Leveraging Pydantic and Plotly/Dash provides a Python first approach (whilst making use of a mostly tech agnostic configuration system).
- (Since Plotly/Dash leverage React components, and allow them to be used as components, then JavaScript can also be used in a form that is effectively wrapped in Python).
| - This empowers a wider group of practitioners that are already close to data analytics, since they are more likely to have existing skills in Python than JavaScript.
- This provides the advantage of leveraging existing Python work spaces such as notebooks and IDEs.
- Facilitates multi-developer collaboration via tools such as Git.
| Python packages are already Python focussed.
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not provide direct or full integration with Python.
Vizro provides a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. |
-| **Open source** - The use of an open source licence, and the reliance on open source packages.
- The provision of ongoing development and maintenance.
| - There is no licence fee required to utilise Vizro.
- Ongoing development and maintenance increases the long term usability of the Vizro package, and viability of implementations.
| Many Python packages also use an open source licence, and provide ongoing development and maintenance.
Vizro is no different in this respect. | Many BI tools follow a licence fee model and/or charge for ongoing development and maintenance.
Vizro requires no licence fee, and provides ongoing development and support, which helps to remove some barriers to usage. |
+| Functionality | Benefits | In context of Python packages | In context of BI tools |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Assembly system** - Configuration-driven assembly system of Vizro automatically builds user-friendly, higher-level dashboard concepts (e.g. a filter) from low-level individual components (e.g. a dropdown component plus a filtering function).
| - Removes the need for users to learn how to write the “glue code” which combines lower-level components.
- Removes the time taken to write, test and optimize the “glue code” which combines lower-level components.
- Reduces what can be 1000s of lines of code down to dozens of lines of configuration.
| Many Python packages still require a moderate understanding of the coding required to assemble higher-level dashboard concepts, which necessitates the creation of “glue code” to combine lower-level components.
Vizro primarily provides a configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly provided by Vizro. |
+| **Inbuilt visual design decisions** - UX decisions such as placement of filters and orientation of charts in relation to other components on the screen.
- Visual design decisions such as chart formatting and spacing between components.
- Colors including text, backgrounds and chart contents.
| - Ensures visual consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on visual design decisions.
- Removes the need for advanced expertise in visual design.
- Ensures basic color accessibility for most likely color combinations.
| Many Python packages provide inbuilt color choices, and visual design choices for certain components.
Vizro applies that to a wide range of component combinations and complex user flows, offering a wholistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customization and flexibility. | Many BI tools provide inbuilt color choices and visual design choices for certain components.
Vizro provides inbuilt visual design for components in addition to the ability to customize them in a flexible way where needed (for example through CSS), and provides automatic arrangement of components on the screen. |
+| **Inbuilt application architecture decisions** - The architectural decisions required to connect components in advanced ways - such as combining connecting filters to charts with multi-screen navigation to allow drill-throughs between screens.
| - Ensures structural consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on architectural decisions or development.
- Removes need for advanced expertise in application architecture.
| Many Python packages provide inbuilt application architecture choices for certain functionalities.
Vizro applies that to a wide range of component combinations and complex user flows, offering a wholistic and comprehensive approach to the entire application architecture, whilst allowing customization and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. |
+| **Declarative configuration, in multiple formats** - Configuration is declarative and can be written in Python or a configuration language such as YAML, JSON and TOML.
| - The range of formats enables flexibility in implementations (and can be extended in future).
- Formats such as YAML support programmatic construction of dashboards (for example being dynamically generated from a Kedro pipeline).
- The focus on editing configuration directly, rather than via GUI or drop-and-drag interfaces, allows for ease of collaboration.
| Many Python packages provide a mostly declarative configuration, with limited ability to leverage multiple formats such as Pydantic models and JSON.
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. |
+| **Mostly tech agnostic “grammar of dashboards”** - The configuration follows a “grammar of dashboards” which is mostly generic and tech agnostic (rather than being specific to any Python package or coding language).
| - Enables a more intuitive understanding of how to write the configuration.
- Enables the configuration to apply to other Python packages or other coding languages in future. (NB: this would require an adjustment to the underlying assembly core code).
| Many Python packages provide an effective “grammar of charts” and Python specific declaration.
Vizro provides a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilize an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro provides an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). |
+| **Inbuilt validation** - The ability to leverage Pydantic models automatically provides meaningful feedback to users about configuration choices.
| - Increases ease of use by guiding users, providing early validation and clear feedback throughout the configuration process.
- This validation feedback can also be utilized by processes which construct the configuration programmatically, such as via a Kedro pipeline.
| Many Python packages provide individual components or non-Pydantic based models.
Vizro provides the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and provide feedback to the manual user to help guide through that process.
Vizro utilizes a flexible system which can be extended to provide feedback to programmatic generation of configuration. |
+| **Modularity** - The standardization applied by Vizro (in terms of visual design, application architecture and coding standards) makes it possible to reuse configuration, charts, components and extensions such as custom actions, between implementations.
| - Speeds up development by allowing reuse of existing implementations.
- Facilitates collaboration between users by allowing knowledge to be encoded in modular ways.
| Many Python packages provide modularity of components such as charts and controls.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools provide extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. |
+| **Flexibility** - The ability to utilize the low-code approach of configuration with the high-code approach of custom functions provides flexibility in implementation for both less technical and more technical users.
| - The low-code configuration driven approach enables all users to create fairly flexible dashboards easily.
- The high-code approach of using custom functions in a structured way provides more technical users with flexibility to extend functionality almost infinitely.
| Many Python packages provide some low-code and/or high-code approaches, which offer varying degrees of flexibility.
Vizro provides a wholistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. |
+| **Scaling** - The consistency in visual design, application architecture and code standards, combined with the ease of collaboration between Python developers, allows scaling within and between projects by facilitating reuse, extension and programmatic updates of configurations.
| - Sections of configuration can be reused and tailored easily, allowing implementations to scale across or between projects.
- New joiners to a team can get up to speed quickly, allowing teams to scale in size.
- Other teams can inherit configurations easily, allowing implementations to scale between teams.
- Updates can be propagated to configurations from a central location, allowing adjustments and updates to scale easily across large implementations.
- Inbuilt visual design decisions provide visual consistency.
- Leveraging collaborative coding mechanisms such as Git enables almost any number of developers to collaborate effectively.
| Many Python packages benefit from the ability to propagate updates programmatically, while applying that to “glue code”.
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. |
+| **Python first** - Leveraging Pydantic and Plotly/Dash provides a Python first approach (whilst making use of a mostly tech agnostic configuration system).
- (Since Plotly/Dash leverage React components, and allow them to be used as components, then JavaScript can also be used in a form that is effectively wrapped in Python).
| - This empowers a wider group of practitioners that are already close to data analytics, since they are more likely to have existing skills in Python than JavaScript.
- This provides the advantage of leveraging existing Python work spaces such as notebooks and IDEs.
- Facilitates multi-developer collaboration via tools such as Git.
| Python packages are already Python focused.
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not provide direct or full integration with Python.
Vizro provides a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. |
+| **Open source** - The use of an open source license, and the reliance on open source packages.
- The provision of ongoing development and maintenance.
| - There is no license fee required to utilize Vizro.
- Ongoing development and maintenance increases the long term usability of the Vizro package, and viability of implementations.
| Many Python packages also use an open source license, and provide ongoing development and maintenance.
Vizro is no different in this respect. | Many BI tools follow a license fee model and/or charge for ongoing development and maintenance.
Vizro requires no license fee, and provides ongoing development and support, which helps to remove some barriers to usage. |
## Cases where alternatives to Vizro are potentially more suitable
diff --git a/vizro-core/docs/pages/user_guides/actions.md b/vizro-core/docs/pages/user_guides/actions.md
index 99457d5a1..8935ae2b1 100644
--- a/vizro-core/docs/pages/user_guides/actions.md
+++ b/vizro-core/docs/pages/user_guides/actions.md
@@ -4,7 +4,7 @@ This guide shows you how to use `Actions`, a new concept in Vizro that is simila
`actions` argument, where you can enter the [`Action`][vizro.models.Action] model.
In a nutshell, using the [`Action`][vizro.models.Action] model together with an `action function` allows you to create complex functionality on a variety of triggers in your dashboard.
-There is already a range of re-usable `action functions` available.
+There is already a range of reusable `action functions` available.
???+ info "Overview of currently available pre-defined `action functions`"
diff --git a/vizro-core/docs/pages/user_guides/assets.md b/vizro-core/docs/pages/user_guides/assets.md
index 11a99fa52..9672229c6 100644
--- a/vizro-core/docs/pages/user_guides/assets.md
+++ b/vizro-core/docs/pages/user_guides/assets.md
@@ -33,7 +33,7 @@ For more information, see [here](https://dash.plotly.com/external-resources#chan
To overwrite any global CSS properties of existing components, target the right CSS property and place your CSS files in the `assets` folder. This will overwrite any existing defaults for that CSS property.
For reference, all Vizro CSS files can be found [here](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css).
-!!! example "Customising global CSS properties"
+!!! example "Customizing global CSS properties"
=== "my_css_file.css"
```css
h1, h2 {
@@ -104,7 +104,7 @@ To achieve this, do the following:
3. Use CSS selectors to target the right property e.g. by leveraging the ID of the outermost Div `"my_card_outer"`
-!!! example "Customising CSS properties in selective components"
+!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
```css
#my_card_outer.card_container {
diff --git a/vizro-core/docs/pages/user_guides/dashboard.md b/vizro-core/docs/pages/user_guides/dashboard.md
index e21a8044d..c17b3ae51 100644
--- a/vizro-core/docs/pages/user_guides/dashboard.md
+++ b/vizro-core/docs/pages/user_guides/dashboard.md
@@ -7,7 +7,7 @@ To create a dashboard, do the following steps:
1. Choose one of the possible configuration syntaxes
2. Create your `pages`, see our guide on [Pages](pages.md)
3. (optional) Choose a `theme`, see our guide on [Themes](themes.md)
-4. (optional) Customise your `navigation`, see our guide on [Navigation](navigation.md)
+4. (optional) Customize your `navigation`, see our guide on [Navigation](navigation.md)
5. (optional) Provide a `title` to your dashboard
6. Add your `dashboard` to the `build` call of Vizro
diff --git a/vizro-core/docs/pages/user_guides/navigation.md b/vizro-core/docs/pages/user_guides/navigation.md
index 37815b25c..441238a91 100644
--- a/vizro-core/docs/pages/user_guides/navigation.md
+++ b/vizro-core/docs/pages/user_guides/navigation.md
@@ -88,7 +88,7 @@ If you want to deviate from the default title `SELECT PAGE` and instead provide
)
```
-!!! example "Customising the navigation panel"
+!!! example "Customizing the navigation panel"
=== "app.py"
```py
from vizro import Vizro
diff --git a/vizro-core/pyproject.toml b/vizro-core/pyproject.toml
index 19ac1376e..265614172 100644
--- a/vizro-core/pyproject.toml
+++ b/vizro-core/pyproject.toml
@@ -27,7 +27,7 @@ dependencies = [
"numpy>=1.22.2", # not directly required, pinned by Snyk to avoid a vulnerability: https://security.snyk.io/vuln/SNYK-PYTHON-NUMPY-2321970
"tornado>=6.3.2", # not directly required, pinned by Snyk to avoid a vulnerability: https://security.snyk.io/vuln/SNYK-PYTHON-TORNADO-5537286
"setuptools>=65.5.1", # not directly required, pinned by Snyk to avoid a vulnerability: https://security.snyk.io/vuln/SNYK-PYTHON-SETUPTOOLS-3180412
- "MarkupSafe" # required to sanitise user input
+ "MarkupSafe" # required to sanitize user input
]
description = "Vizro is a package to facilitate visual analytics."
dynamic = ["version"]
diff --git a/vizro-core/src/vizro/_vizro.py b/vizro-core/src/vizro/_vizro.py
index b2becbd78..1b2996585 100644
--- a/vizro-core/src/vizro/_vizro.py
+++ b/vizro-core/src/vizro/_vizro.py
@@ -20,7 +20,7 @@ class Vizro:
_lib_assets_folder = os.path.join(os.path.dirname(os.path.abspath(__file__)), "static")
def __init__(self):
- """Initialises Dash."""
+ """Initializes Dash."""
_js, _css = _append_styles(self._lib_assets_folder, STATIC_URL_PREFIX)
self.dash = Dash(
use_pages=True,
diff --git a/vizro-core/src/vizro/actions/_filter_action.py b/vizro-core/src/vizro/actions/_filter_action.py
index c07aa05b8..4516a96dd 100644
--- a/vizro-core/src/vizro/actions/_filter_action.py
+++ b/vizro-core/src/vizro/actions/_filter_action.py
@@ -1,4 +1,4 @@
-"""Pre-defined action function "_filter" to be re-used in `action` parameter of VizroBaseModels."""
+"""Pre-defined action function "_filter" to be reused in `action` parameter of VizroBaseModels."""
from typing import Any, Callable, Dict, List
diff --git a/vizro-core/src/vizro/actions/_on_page_load_action.py b/vizro-core/src/vizro/actions/_on_page_load_action.py
index 06bff8e0e..28e513b31 100644
--- a/vizro-core/src/vizro/actions/_on_page_load_action.py
+++ b/vizro-core/src/vizro/actions/_on_page_load_action.py
@@ -1,4 +1,4 @@
-"""Pre-defined action function "_on_page_load" to be re-used in `action` parameter of VizroBaseModels."""
+"""Pre-defined action function "_on_page_load" to be reused in `action` parameter of VizroBaseModels."""
from typing import Any, Dict
diff --git a/vizro-core/src/vizro/actions/_parameter_action.py b/vizro-core/src/vizro/actions/_parameter_action.py
index 97f66d681..caf9faebf 100644
--- a/vizro-core/src/vizro/actions/_parameter_action.py
+++ b/vizro-core/src/vizro/actions/_parameter_action.py
@@ -1,4 +1,4 @@
-"""Pre-defined action function "_parameter" to be re-used in `action` parameter of VizroBaseModels."""
+"""Pre-defined action function "_parameter" to be reused in `action` parameter of VizroBaseModels."""
from typing import Any, Dict, List
diff --git a/vizro-core/src/vizro/actions/export_data_action.py b/vizro-core/src/vizro/actions/export_data_action.py
index 09b73423e..5af593235 100644
--- a/vizro-core/src/vizro/actions/export_data_action.py
+++ b/vizro-core/src/vizro/actions/export_data_action.py
@@ -1,4 +1,4 @@
-"""Pre-defined action function "export_data" to be re-used in `action` parameter of VizroBaseModels."""
+"""Pre-defined action function "export_data" to be reused in `action` parameter of VizroBaseModels."""
from typing import Any, Dict, List, Optional
diff --git a/vizro-core/src/vizro/actions/filter_interaction_action.py b/vizro-core/src/vizro/actions/filter_interaction_action.py
index ceb1c96b6..51321a8ab 100644
--- a/vizro-core/src/vizro/actions/filter_interaction_action.py
+++ b/vizro-core/src/vizro/actions/filter_interaction_action.py
@@ -1,4 +1,4 @@
-"""Pre-defined action function "filter_interaction" to be re-used in `action` parameter of VizroBaseModels."""
+"""Pre-defined action function "filter_interaction" to be reused in `action` parameter of VizroBaseModels."""
from typing import Any, Dict, List, Optional
diff --git a/vizro-core/src/vizro/models/_action/_actions_chain.py b/vizro-core/src/vizro/models/_action/_actions_chain.py
index b352c46a5..57f193190 100644
--- a/vizro-core/src/vizro/models/_action/_actions_chain.py
+++ b/vizro-core/src/vizro/models/_action/_actions_chain.py
@@ -16,7 +16,7 @@ class ActionsChain(VizroBaseModel):
actions: List[Action] = []
-# Validators for re-use in other models to convert to ActionsChain
+# Validators for reuse in other models to convert to ActionsChain
def _set_actions(actions: List[Action], values: Dict[str, Any], trigger_property: str) -> List[ActionsChain]:
return [
ActionsChain(
diff --git a/vizro-core/src/vizro/models/_components/form/_form_utils.py b/vizro-core/src/vizro/models/_components/form/_form_utils.py
index a36347cf1..2be53ef3c 100644
--- a/vizro-core/src/vizro/models/_components/form/_form_utils.py
+++ b/vizro-core/src/vizro/models/_components/form/_form_utils.py
@@ -30,7 +30,7 @@ def is_value_contained(value: Union[SingleValueType, MultiValueType], options: O
return value in options
-# Validators for re-use
+# Validators for reuse
def validate_options_dict(cls, values):
"""Reusable validator for the "options" argument of categorical selectors."""
if "options" not in values or not isinstance(values["options"], list):
diff --git a/vizro-core/src/vizro/models/_navigation/navigation.py b/vizro-core/src/vizro/models/_navigation/navigation.py
index 26fb9cffd..56d03c99d 100644
--- a/vizro-core/src/vizro/models/_navigation/navigation.py
+++ b/vizro-core/src/vizro/models/_navigation/navigation.py
@@ -14,7 +14,7 @@
from vizro.models._navigation._accordion import Accordion
-# Validator for re-use in other models to validate pages
+# Validator for reuse in other models to validate pages
def _validate_pages(pages):
from vizro.models import Page
diff --git a/vizro-core/tests/unit/vizro/models/test_base.py b/vizro-core/tests/unit/vizro/models/test_base.py
index 4d26a1376..84bafd561 100644
--- a/vizro-core/tests/unit/vizro/models/test_base.py
+++ b/vizro-core/tests/unit/vizro/models/test_base.py
@@ -93,7 +93,7 @@ def test_add_type_dict_instantiation(self, Parent):
class TestOptionalDiscriminatedUnion:
# Optional[ChildType] does not work correctly as a discriminated union - pydantic turns it into a regular union.
# Hence the validation error messages are not as expected. The tests of add_type pass because in practice a
- # discriminated union is not actually needed to achieve the desired behaviour. The union is still a regular one
+ # discriminated union is not actually needed to achieve the desired behavior. The union is still a regular one
# even after add_type.
@pytest.mark.xfail
def test_no_type_match(self, ParentWithOptional):