Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

73: add client.entities.update #84

Merged
merged 2 commits into from
May 13, 2024
Merged

Conversation

lindsay-stevens
Copy link
Contributor

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

- add: entity fields that were not included earlier:
  - entity.conflict
  - entity.currentVersion.createdAt
  - entity.currentVersion.data (None for entities.list())
- chg: use plain uuid4() instead of uuid:uuid4() to match Central
@lognaturel
Copy link
Member

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!

Copy link
Member

@lognaturel lognaturel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As described above

- chg: label or data (or both/neither) are allowed for entities.update
- add: readme section on default identifiers
@lindsay-stevens
Copy link
Contributor Author

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.

Copy link
Member

@lognaturel lognaturel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉 🎉

@lognaturel lognaturel merged commit 47cf2cf into getodk:master May 13, 2024
4 checks passed
@lindsay-stevens lindsay-stevens deleted the pyodk-73 branch May 22, 2024 03:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add entity update
2 participants