.. -*-coding: utf-8-*- .. role:: color-violet .. role:: color-red ************ Installation ************ ======================================= Installing a Virtual Python Environment ======================================= ------------------------- Why a Virtual Environment ------------------------- Python virtual environments are used regularly by seasoned Python programmers however, beginners may not know about this feature rich tool. Virtualenv is a tool which allows the creation of isolated python environments. So what do we get from isolated environments? Lets say you are developing a project that needs version 1 of some library. You install it globally on your computer. A while later you start work on another project that requires the same library, but version 2. If you install version 2 globally, as you did before, it may break the first project you were working on. This is where virtual environments comes to the rescue, every project is in it's own isolated environment and you no longer need to install python packages as sudo (root) user. Which means the other advantage of virtual environments is that it's installed in your user account not in the root of the system. This API was tested to work with Python versions 3.10 to 3.14. I strongly recommend writing any new code with the latest version of Python. ---------------------------------------------------- Building a Development Environment for your Projects ---------------------------------------------------- This build information works on Debian derived Linux operating systems such as Ubuntu, Linux Mint, Kaii Linux, and others. .. code-block:: console $ sudo apt install build-essential python3.14 python3-setuptools \ git virtualenvwrapper The ``virtualenvwrapper`` package is a wrapper around ``virtualenv`` that provides easy to use tools for ``virtualenv`` and will install ``virtualenv`` for you. .. note:: A directory is created in the user's home directory named ``.virtualenvs``. In there you'll be able to find all your project requirements and the packages you have installed for each of them. Configure ``.bashrc`` in your user directory to auto load the ``virtualenvwrapper`` package. .. code-block:: console $ nano .bashrc Then add the following lines to the bottom of the ``.bashrc`` file. .. code-block:: bash # Setup the Python virtual environment. VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 source /usr/share/virtualenvwrapper/virtualenvwrapper.sh $ . .bashrc # 'source .bashrc' Works also Create a VE (Virtual Environment) for your project. The VE name can be whatever you want and does not need to match the actual project's name, but it might be a good idea to keep it short so that you can remember it. Use whichever Python version you have in the command below. .. code-block:: console $ cd /path/to/your_project $ mkvirtualenv -p python3.14 After the initial creation of the VE you can use these commands to activate and deactivate a VE. .. code-block:: console $ workon $ deactivate Next you will need to install all the Python packages that your project depends on. Many of them will be in the pip repository at `PyPi Repository `_. ======================= Installing badidatetime ======================= To install ``badidatetime`` in your virtual environment enter the following on the command line. Be sure your virtual environment is activated before doing this. .. code-block:: console $ pip install badidatetime or $ pip install git+https://github.com/cnobile2012/bahai-calendar.git If you are working on ``badidatetime`` itself, you'll need to install the ``development.txt`` file mentioned below. You may want to fork my version first. This is advanced usage so you and will need to have your own GitHub account for this to work properly. .. code-block:: console $ cd /path/to/where/your/project/will/be/rooted $ git clone git@github.com:cnobile2012/bahai-calendar.git If all the correct system packages have been installed you can now setup the virtual environment that ``badidatetime`` requires. **Change the Python version below to the one you are using.** .. code-block:: console $ mkvirtualenv -p python3.14 calendar $ workon calendar $ pip install -r requirements/development.txt That should be it. If you have any issues please check all the instructions before contacting me. ===================== Building badidatetime ===================== .. note:: This part is only needed by me and people that have forked the repository and want to contribute to this project. Versions are controlled by the **include.mk** file, so this is the only place to change version information. This file is read by various scripts in the repository. In other words *DO NOT* update the **pyproject.toml** directly, there is a script (config.py) that is run from the **Makefile** that will update everything correctly. The (config.py) script also updates the `__version__` variable in the `badidatetime.__init__.py` file. Follow these steps to create the correct versioning and package for uploading to `pypi`. 1. Run local tests, if they failed fix any issues before going to 2 below. 2. Update the **include.mk** file with the new version information. 3. Manually run the `config.py` script so the version gets updated in the `badidatetime.__init__.py` file. .. code-block:: console $ ./config.py 4. Commit and push all code relating to the new release. 5. Check that the `GitHub` tests pass, if you've set them up. 6. Create the version tag for the branch you are working in and push. .. code-block:: console $ git tag -a -m "Comment about this tag." $ git push origin 7. Upload to the `pypi` test site. .. code-block:: console $ make upload-test TEST_TAG=rc1 8. Go to your account on the `pypi test site `_ to check if it is there. :color-red:`(For errors see below.)` 9. After the `pyproject.toml` file gets updated to the `pypi` test and main sites, so it will need to be committed and pushed separately. This file is not in the `badidatetime` build so it can lag behind with no problems. 10. Assuming everything went as expected then upload to the main `pypi` site. .. code-block:: console $ make upload 11. Go to your account on the `pypi site `_ to check if it is there. 12. Done, the new version is published. If errors occurred during the upload to the test `pypi` site you will need to fix files and check in again. The tag created above will need to be moved to the *HEAD* of the branch afterwards. 1. Run local tests. 2. Commit and push all code relating to any errors found. 3. Check that the `GitHub` tests pass. 4. Move the version tag. :color-red:`The commit hash can be just the first 7 characters of the full hash.` .. code-block:: console $ git log | less # The value after the 'commit' keyword is the hash. $ git tag -a -f -m "Comment" $ git push origin --tags -f 5. Then continue with number 7 above.