This guide shows how to compile and test this project. Anyone who want to contribute to these codes can follow this guide and submit the pull request. Section 2 🔖 and Section 3 🔖 suggests how to work with Docker or Conda, respectively. Please choose either of these tools to deploy the environment and develop this project.

• Review our code of conduct 📝 before contributing to this project.

• The metadata of the project is defined in pyproject.toml and package.json. Modifying package.json will not automatically update pyproject.toml. Therefore, users need to ensure changes for both files if any part of the metadata needs to be changed.

• The React source files are in the src/lib/ folder. These codes are formatted by pretteir🔨.

• The Python codes are in the package dash_file_cache/ folder. These codes are formatted by black🔨.

• The Python Compoenent codes are in the sub-package dash_file_cache/components/ folder. Note that the automatically generated files like _imports_.py and Downloader.py will not be formatted.

• Currently, we do not provide the React demo application. Therefore, please do not use yarn start.

• The Dash demo apps are stored in examples/. These demos show the usages this package in different cases.

• The unit tests are defined in the tests/ folder.

• The version/ folder is only used for helping pyproject.toml fetch the current version.

• The tool configurations for pytest, black, and pyright are defined in pyproject.toml. However, the configurations for flake8, pylint, and prettier are still kept in their corresponding configurations files.

• If any custom styles are defined but not imported as a part of the react codes, please add these custom CSS files into the distribution folder (dash_json_grid).

  • Make sure that they are referenced in MANIFEST.in so that they get properly included when you're ready to publish your component.
  • Make sure the stylesheets are added to the _css_dist dict in dash_json_grid/__init__.py so dash will serve them automatically when the component suite is requested.

• Remember to use black🔨 and pretteir🔨 to format any modified Python and React codes, respectively. Review your code 📝 before sending the pull request.

If you choose to use Docker. The only software you need to install is docker itself. Check the following guide to install Docker on your device:

https://docs.docker.com/get-started/get-docker/

After installing docker, test whether it works or not by

docker run -it --rm hello-world

You should be able to see the message like this, which shows that docker is working well:

Then, build the docker image by

docker build -t dash-file-cache:latest https://github.com/cainmagi/dash-file-cache.git

This step may take a little bit long. After successfully building the image, you can start working on this project.

Run the following command to start the tests.

docker run -it --rm dash-file-cache:latest --with-dash

If the codes have not been modified, you suppose to see the the messages like this:

It shows that all unit tests get passed.

We have prepared several Dash demos. Run this command to launch the default demo (./examples/change_image.py):

docker run -it --rm -p 8080:8080 dash-file-cache:latest --demo

The following command is used for launching a different demo. The available demo names are the .py file names in ./examples

docker run -it --rm -p 8080:8080 dash-file-cache:latest --demo demo=change_image

When the demo is running, you should be able to access the demo by

http://localhost:8080/

To modify the scripts, you may want to clone an Git repository by yourself:

git clone https://github.com/cainmagi/dash-file-cache

Then, you can run the docker container and mount the newly cloned Git folder to the container:

docker run -it --rm -v <path-to-the-project>:/workdir -p 8080:8080 dash-file-cache:latest --bash

When the container is running, you should be able to see that your are in the container's console.

Please leave the container open, and follow this guide to attach your vscode to the running container:

https://code.visualstudio.com/docs/devcontainers/attach-container

At the bottom left corner, you should be able to see the name of the current container. When you open a new workspace, you should be able to find the the project in /workdir.

Now you will be able to start the development. You can do the following things to test the codes.

• Build the component

  yarn install
  yarn build

• Run the pytest:

  python -m pytest --headless --with-dash

• Run the demo:

  python examples/change_image.py

• Format the python codes

  black .

• Build the python pacakge

  python -m build

Before submitting a pull request, please ensure that all unit tests (pytest) get passed and the codes are formatted by black.

Before start the installation, you need to ensure the following things are installed:

• Conda or Mamba

  Either MiniConda or MicroMamba is a good option. MicroMamba is even faster than MiniConda. If you choose to use micromamba, you simply need to replace conda by micromamba in any command.

  • Get MiniConda: https://docs.anaconda.com/miniconda/miniconda-install/
  • Get MicroMamba: https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html

• A browser

  You need to ensure that either one of the Chromium-based browser is installed.

  • Get Edge: https://www.microsoft.com/en-us/edge/download
  • Get Chrome: https://www.google.com/chrome/dr/download
  • Get Chromium: https://www.chromium.org/getting-involved/download-chromium/

• Git

  You need to ensure that Git command is available:

  • Get Git: https://git-scm.com/downloads

Use Git to clone the latest source codes:

git clone https://github.com/cainmagi/dash-file-cache

The following steps will help you configure the environment with conda:

1. Create the environment

   conda create -c conda-forge -n dashdev-dfc python=3.12 wheel setuptools nodejs yarn

2. Enter the environment

   conda activate dashdev-dfc

3. Install the Python dependencies

   pip install -r requirements.txt -r requirements-dev.txt -r tests/requirements.txt

4. Install the Node.js dependencies and build the first version.

   yarn install
   yarn build

To verify whether you have correctly prepared the environment or not, you can run the following command:

python -m pytest --headless --with-dash

You can do the following things to test the codes.

• Build the component

  yarn install
  yarn build

• Run the pytest:

  python -m pytest --headless --with-dash

• Run the demo:

  python examples/change_image.py

• Format the python codes

  black .

• Build the python pacakge

  python -m build

Before submitting a pull request, please ensure that all unit tests (pytest) get passed and the codes are formatted by black.