73: add client.entities.update

[lindsay-stevens]

Closes #73

What has been done to verify that this works as intended?

New unit and integration tests.

Why is this the best possible solution? Were any other approaches considered?

Added function is as specified in #73. One minor assumption: an error is raised if both force and base_version are provided. It seemed like that might be dangerous as well, e.g. user specifies the wrong base_version but gets an update anyway.

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

New convenience method.

Do we need any specific form for testing your changes? If so, please attach one.

N/A

Does this change require updates to documentation? If so, please file an issue here and include the link below.

No

Before submitting this PR, please make sure you have:

• included test cases for core behavior and edge cases in tests
• run python -m unittest and verified all tests pass
• run ruff format pyodk tests and ruff check pyodk tests to lint code
• verified that any code or assets from external sources are properly credited in comments

[lognaturel]

an error is raised if both force and base_version are provided

Yes, absolutely, thanks!

I think the parameter order should be

     def update(
        self,
        uuid: str,
        project_id: int | None = None,
        entity_list_name: str | None = None,
        label:  str | None = None,
        data: dict | None = None,
        force: bool | None = None,
        base_version: int | None = None,
    ) -> Entity:

It's a relatively minor thing but I do think the parameter order can help with comprehension. In general, if a method updates a resource, I would expect that resource's identifier (the entity uuid) to come first. Similarly, I think it's helpful to have parameters that identify where in the hierarchy the resource is (project_id and entity_list_name) before other optional parameters. It's really kind of too bad that those have to be marked as optional since they do have to be set somewhere. At some point we should probably explain this somewhere in the docs but I'm not sure where yet!

I also updated the types -- it's possible and reasonable to only update one of label or data. I think it's ok to make them both optional and not do anything else. We could also error if neither is provided like with force/base_version, up to you!

[lognaturel]

As described above

[lindsay-stevens]

Thanks! I updated the params to be optional. There might be some reason to send empty entity updates now or in future (e.g. to update the version only?) so I didn't include an error for them being both blank. Also added a readme note about identifiers.

[lognaturel]

🎉 🎉