For beginners

[nafanz]

How about a beginner's guide?

I have some experience with Python (hobby projects), but not with big projects.

I'm interested in testing my skills when performing light tasks.

I'm currently stumped by the environment preparation, I use pip install -r requirements.txt the old-fashioned way, but I don't see the usual file for installing dependencies in the project.

There is pyproject.toml, as I understand it is used by poetry, I have never worked with it before. Searching the Internet led me to the following installation option:

pipx install poetry
  installed package poetry 2.0.1, installed using Python 3.12.3
  These apps are now globally available
    - poetry
done! ✨ 🌟 ✨

I also cloned the repository and created a virtual environment for it.

After that I try to install dependencies and get:

poetry install

The Poetry configuration is invalid:
  - Either [project.version] or [tool.poetry.version] is required in package mode.

Information about what I use:

• Ubuntu 24.04.1 LTS
• PyCharm Community 2024.3.1
• Python 3.12.3

Sorry for the trivial question.

[da4089]

The best current documentation is available at https://vobject.readthedocs.io/latest/. In particular, the "Quick Start" chapter should cover your setup, but I'm sure it can be better ...

You should first ensure you have Python installed, version 3.9 or later. It mostly doesn't matter how you do this: however you'd normally install software. For Windows the installer from python.org is a good option, but for Ubuntu you should just use apt (although it's probably already installed -- you said Python 3.12, which will be great).

Note that some Python tools manage both Python code and the Python interpreter installation as well. I think pipx and uv both do this, for example. Unless you know you want to use these tools, I would not do this to start.

Second step is to create a virtual environment. How you do that again depends on what tools you choose to use. The default is to use venv, like python -m venv venv

And then activate it, using source venv/bin/activate (or call venv\scripts\activate.bat on Windows). You should find more details about doing this in one of the million Python tutorials available.

If you're using PyCharm, you could use its methods of creating a virtual environment instead? Either way should be fine.

Now you're ready to install vobject. Are you wanting to write programs that use vobject? If so, you can simply do pip install vobject -- pip will install all the dependencies for you.

There's no need to manually install dependencies, and no need for Poetry: pip understands pyproject.toml files (as will most Python tools).

[nafanz]

Sorry, I guess I wasn't clear in the question. I mean the contributor's guide on how to set up the development environment.

Searching led me to this:

• Download dependencies declared in pyproject.toml using Pip
• When would the -e, --editable option be useful with pip install?

Installed dependencies in edit mode and updated pip:

(venv) qa@qa-Z87M-D3H:~/vobject$ pip install -e .
Obtaining file:///home/qa/vobject
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... done
Collecting python-dateutil>=2.7.0 (from vobject==1.0.0)
  Obtaining dependency information for python-dateutil>=2.7.0 from https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata
  Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB)
Collecting pytz>=2019.1 (from vobject==1.0.0)
  Obtaining dependency information for pytz>=2019.1 from https://files.pythonhosted.org/packages/11/c3/005fcca25ce078d2cc29fd559379817424e94885510568bc1bc53d7d5846/pytz-2024.2-py2.py3-none-any.whl.metadata
  Using cached pytz-2024.2-py2.py3-none-any.whl.metadata (22 kB)
Collecting six>=1.5 (from python-dateutil>=2.7.0->vobject==1.0.0)
  Obtaining dependency information for six>=1.5 from https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl.metadata
  Using cached six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Using cached pytz-2024.2-py2.py3-none-any.whl (508 kB)
Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
Building wheels for collected packages: vobject
  Building editable for vobject (pyproject.toml) ... done
  Created wheel for vobject: filename=vobject-1.0.0-py3-none-any.whl size=9188 sha256=d2fa710c564c5b9fdad2b57e2c01f5b4deff06cd0b5539e83e6f080cbbdf133f
  Stored in directory: /tmp/pip-ephem-wheel-cache-hu40no25/wheels/c2/7c/2d/e4e17ee0465166ed892acaa4395015a4b68e2ead451d39102a
Successfully built vobject
Installing collected packages: pytz, six, python-dateutil, vobject
Successfully installed python-dateutil-2.9.0.post0 pytz-2024.2 six-1.17.0 vobject-1.0.0

[notice] A new release of pip is available: 23.2.1 -> 25.0
[notice] To update, run: pip install --upgrade pip
(venv) qa@qa-Z87M-D3H:~/vobject$ pip install --upgrade pip
Requirement already satisfied: pip in ./venv/lib/python3.12/site-packages (23.2.1)
Collecting pip
  Obtaining dependency information for pip from https://files.pythonhosted.org/packages/85/8a/1ddf40be20103bcc605db840e9ade09c8e8c9f920a03e9cfe88eae97a058/pip-25.0-py3-none-any.whl.metadata
  Downloading pip-25.0-py3-none-any.whl.metadata (3.7 kB)
Downloading pip-25.0-py3-none-any.whl (1.8 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.8/1.8 MB 5.3 MB/s eta 0:00:00
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 23.2.1
    Uninstalling pip-23.2.1:
      Successfully uninstalled pip-23.2.1
Successfully installed pip-25.0

I'm trying to run tests through IDE:

/home/qa/vobject/venv/bin/python /snap/pycharm-community/439/plugins/python-ce/helpers/pycharm/_jb_unittest_runner.py --path /home/qa/vobject/tests 
Testing started at 09:56 ...
Launching unittests with arguments python -m unittest discover -s /home/qa/vobject/tests -t /home/qa/vobject/tests in /home/qa/vobject/tests


Error
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 33, in testFailure
    raise self._exception
ImportError: Failed to import test module: test_icalendar
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 394, in _find_test_path
    module = self._get_module_from_name(name)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/unittest/loader.py", line 337, in _get_module_from_name
    __import__(name)
  File "/home/qa/vobject/tests/test_icalendar.py", line 6, in <module>
    import pytest
ModuleNotFoundError: No module named 'pytest'



Error
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 33, in testFailure
    raise self._exception
ImportError: Failed to import test module: test_vobject
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 394, in _find_test_path
    module = self._get_module_from_name(name)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/unittest/loader.py", line 337, in _get_module_from_name
    __import__(name)
  File "/home/qa/vobject/tests/test_vobject.py", line 3, in <module>
    import pytest
ModuleNotFoundError: No module named 'pytest'



Error
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 33, in testFailure
    raise self._exception
ImportError: Failed to import test module: test_vobject_parsing
Traceback (most recent call last):
  File "/usr/lib/python3.12/unittest/loader.py", line 394, in _find_test_path
    module = self._get_module_from_name(name)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/unittest/loader.py", line 337, in _get_module_from_name
    __import__(name)
  File "/home/qa/vobject/tests/test_vobject_parsing.py", line 3, in <module>
    import pytest
ModuleNotFoundError: No module named 'pytest'




Ran 3 tests in 0.005s

FAILED (errors=3)

Process finished with exit code 1

First I want to run tests, this is my indicator that I did everything correctly and can move on.

I understand that the error says that I don't have pytest installed and I can probably do it manually. But I expected that running the command pip install -e . would install all dependencies automatically. What am I doing wrong?

[da4089]

To install for development of vobject itself (instead of developing with vobject), you should use pip install -e '.[dev]'.

In the pyproject.toml, you can see there's a "project.optional-dependencies" section, which adds the extra things needed to do development on vobject, including pytest.

[nafanz]

Thank you, this is exactly what I needed.

Again, sorry for the stupid questions, but this is really confusing.

https://github.com/py-vobject/vobject/blob/master/CONTRIBUTING.md
Since the only document for new members that I found says nothing about this.

[da4089]

Could you please log an issue to get that updated?

[nafanz]

Okay, I'll do that a bit later. I might also try to file my first pull request to update this documentation. If that's okay with you.

[da4089]

Sure, that'd be great!

[da4089]

It also looks like PyCharm is trying to run the pytest-based tests using unittest (which I think won't work).

I cloned vobject into a temporary working area, and set the Python interpreter to my laptop's install of 3.12, and created a new "Virtualenv" environment for the project (via PyCharm).

When I right-click on the "tests" directory in the project's file panel, I get a "Run purest in tests" option (and a matching debug option). Running that fails (as expected) because it cannot find pytest.

I can't find a way to have PyCharm install the dependencies from the pyproject.toml, so I think you'll have to do that via a terminal window.

Once I'd done that, right-click on the tests directory, and running or debugging tests, seems to work for me.

[da4089]

Also, just so you know, test_pytz_timezone_serializing might take a while to run (17s on my last run). That's expected for now.

[nafanz]

After installing the dependencies for development (as per your advice), running tests with IDE was successful. No additional actions were required. It only crashed, but this is a problem of the test itself.

tests/test_icalendar.py:546 (test_omits_dst_offset)
key = 'US/Eastern'

    def load_tzdata(key):
        from importlib import resources
    
        components = key.split("/")
        package_name = ".".join(["tzdata.zoneinfo"] + components[:-1])
        resource_name = components[-1]
    
        try:
>           return resources.files(package_name).joinpath(resource_name).open("rb")