feat(folders): implement list_folders_v2 for API v2 support (#140)

[DEVANSH-GAJJAR]

Description

This PR implements the list_folders_v2 method in fossology/folders.py to extend support for the Fossology API v2.

Currently, the wrapper defaults to v1 endpoints. This implementation allows users to fetch folder lists using the new v2 structure by dynamically adjusting the API base URL.

Changes

• Added list_folders_v2 method to the Folders class.
• Implemented URL logic to switch from .../api/v1 to .../api/v2 dynamically.
• Added response parsing to handle the V2 JSON list format and return Folder objects.

Related Issue

Relates to #140

Testing & Verification

• Static Analysis: Verified syntax validity (py_compile) and successful import (from fossology.folders import Folders).
• Unit Tests: I encountered some local environment issues setting up the pytest mock server infrastructure.
  • Note to Reviewers: I have opened this PR to get feedback on the implementation logic first. I am happy to add the responses mock test once I resolve the local setup or with guidance on the preferred testing pattern for v2.

Checklist

• My code follows the code style of this project.
• I have updated the documentation (docstrings) accordingly.
• I have read the CONTRIBUTING document.

[deveaud-m]

@DEVANSH-GAJJAR welcome to Fossology Python and thanks for starting this PR.

I would like to avoid duplicating all the methods just to support v2 because I think most of the content will be similar, only some endpoints will only be available for one version or the other.

I started doing a little bit of refactoring in preparation to supporting v2 in this PR: https://github.com/fossology/fossology-python/pull/162/files#diff-df2ec7af328aecf9da4e6ef7c9d4a7515e50c73a692d5857c8fc20f970bd3068R133.

The targeted version shall be given during instanciation of the Fossology class using the version parameter.

If the response diverge between v1 and v2, we should use a slightly adapted object factory, e.g.:

# fossology/obj.py
class FolderFactory:
    @staticmethod
    def from_json(version, data):
        if version == "v2":
            return Folder.from_json_v2(data)
        return Folder.from_json(data)
...
class Folders:
    """Class dedicated to all "folders" related endpoints"""

    def list_folders(self):
        response = self.session.get(f"{self.api}/folders")
        if response.status_code == 200:
            folders_list = list()
            response_list = response.json()
            for folder in response_list:
				if self.version == "v2":
                	sub_folder = FolderFactory.from_json_v2(self.version, folder)
				else:
					sub_folder = FolderFactory.from_json(self.version, folder)
                folders_list.append(sub_folder)
            return folders_list
        else:
            description = f"Unable to get a list of folders for {self.user.name}"
            raise FossologyApiError(description, response)

Could you give it a shot once you rebased on top of #162?

[DEVANSH-GAJJAR]

Hi there @deveaud-m ,
could you please trigger the CI checks or let me know if any further changes are needed from my side?

[deveaud-m]

Hi there @deveaud-m , could you please trigger the CI checks or let me know if any further changes are needed from my side?

@DEVANSH-GAJJAR Unfortunately some tests are failing, I suppose the logic of the endpoint changed between v1 and v2.

Are you able to test the endpoints locally on your machine? This should help get the tests correctly.

Let me know if you need help and if I shall take over this PR.

[DEVANSH-GAJJAR]

Thanks for checking and for the suggestion.

You’re right — the behavior differs between v1 and v2. I’ve identified that the current CI failures are due to missing mocks for the /api/v2/folders endpoints rather than an issue with the endpoint logic itself. I’m testing this locally and updating the tests/mocks accordingly. I’ll push the fixes shortly.

Thanks a lot for offering help — I’d like to take care of this and will reach out if I need assistance.

[DEVANSH-GAJJAR]

Hi @deveaud-m , all the previous issues have been fixed and all tests are now passing.

The only CI failure is a codecov token issue in the workflow, unrelated to the code changes.

Please review when you get a chance!

[deveaud-m]

@DEVANSH-GAJJAR the implementation looks good now and tests are now successful so I would be ready to get it in.

Could you finally rewrite the commit history to separate the formatting changes from the functional changes? I'll merge the change afterwards.

[DEVANSH-GAJJAR]

Hi @deveaud-m , I have made the changes you requested and re-written into the commit history. The branch is ready to merge .

thanks !!

[deveaud-m]

@DEVANSH-GAJJAR please rebase on the main branch instead of merging changes in 76676bf

What I was expecting is one commit integration all the changes related to formatting and one commit with the changes related to the functional changes.

Some formatting and testing issues remains still, see the action output.

[DEVANSH-GAJJAR]

Hi @deveaud-m , successfully rebased on main. All 14 folder tests pass perfectly. There's 1 pre-existing flaky test (test_upload_for_group) unrelated to folder changes. The folder implementation is complete and ready for review!