Update README.md

[mattkeanny]

Removed input format 'original' from example comment. Acc. to the OPS guide, section 2.1.2, the 'original' format is used only by the OPS number-service (section 3.3) hence only confusing in combination with the published_data() method.

[gsong]

@mattkeanny As far as I understand you can use any of the three numbering formats interchangeably, is there a disadvantage to calling out that you can use epo_ops.models.Original?

Or are you saying that published_data() won't work with an original number?

(Sorry, it's been a while since I've worked with EPO data, so I'm rusty).

[mattkeanny]

@gsong Indeed published_data() does not work with an original number format, only with the docdb and epodoc.
In the OPS guide it is documented only in side-notes here and there (like in section 2.1.2).

Tested the ops api on the ops developers site using original as the input format just to confirm it (the the only service that works with the original format acc. to the ops guide is the Number Service):

/published-data/publication/original/EP.(1 000 000)/... -> fails
/number-service/publication/original/EP.(1 000 000)/... -> works

[amotl]

Hi Matt.

This is interesting, thanks for sharing, and for your patch. Now, I am thinking about whether the library should also respect this fact, and reject that operation by raising an appropriate exception educating the user correspondingly.

With kind regards,
Andreas.

NB: On the failing CI checks, I will try to submit a patch that will take into account that PRs submitted by external contributors do not have access to the credentials/secrets deposited at GHA, in this case OPS_KEY. Please do not merge this PR yet, as we can use it as an exercise to validate this improvement.

[mattkeanny]

This is interesting, thanks for sharing, and for your patch. Now, I am thinking about whether the library should also respect this fact, and reject that operation by raising an appropriate exception educating the user correspondingly.

Makes sense indeed. Would spare a user pondering over the meaning of the returned 404 error.

[mattkeanny]

@amotl: Skimming through the ops guide, section 4.5 reads:

As OPS provides access to data that is held inside the EPO, the OPS services (except
the number-service) require the input to be in one of the two EPO formats: epodoc or
docdb. The most common use case of the number-service is thus to transform numbers
that are given in domestic formats of different countries to the EPO formats that can
then be used for receiving published, family, register, legal or classification data.

which would tend to reinforce your suggestion to raise an early exception when using original in any method except the number() method.

[gsong]

@amotl: Skimming through the ops guide, section 4.5 reads:

As OPS provides access to data that is held inside the EPO, the OPS services (except
the number-service) require the input to be in one of the two EPO formats: epodoc or
docdb. The most common use case of the number-service is thus to transform numbers
that are given in domestic formats of different countries to the EPO formats that can
then be used for receiving published, family, register, legal or classification data.

which would tend to reinforce your suggestion to raise an early exception when using original in any method except the number() method.

Added #84.

@mattkeanny In this PR, would you be willing to change client method table https://github.com/ip-tools/python-epo-ops-client?tab=readme-ov-file#client to include a checkbox "Works with Original" column? Or something similar that conveys the spirit of this discussion?

[mattkeanny]

@gsong I would prefer not to "overcrowd" the table, which to me looks succinct. I think this could go nicely into api docs and docstrings?

[gsong]

@gsong I would prefer not to "overcrowd" the table, which to me looks succinct. I think this could go nicely into api docs and docstrings?

That sounds reasonable. Feel free to tack on to the issue or add another issue.

[amotl]

Please do not merge this PR yet, as we can use it as an exercise to validate this improvement.

Hi. GH-86 has a corresponding patch. After merging it, and rebasing, this PR should also signal a successful outcome on CI.

Edit: Merged. Please rebase.

[amotl]

I've rebased through GitHub UI, and will merge the patch now.

[CholoTook]

@gsong I would prefer not to "overcrowd" the table, which to me looks succinct. I think this could go nicely into api docs and docstrings?

I'm so sorry, I'm coming at all this as an outsider... I'm literally searching issues to help me find documentation 😅

You mention the client method table being succinct, but I'm having a hard time understanding it.. Somewhere could you provide an example of how to call one of the rows?

Shall I create a separate issue for this ... issue?

Many thanks,

[mattkeanny]

@gsong I would prefer not to "overcrowd" the table, which to me looks succinct. I think this could go nicely into api docs and docstrings?

I'm so sorry, I'm coming at all this as an outsider... I'm literally searching issues to help me find documentation 😅

You mention the client method table being succinct, but I'm having a hard time understanding it.. Somewhere could you provide an example of how to call one of the rows?

Shall I create a separate issue for this ... issue?

Many thanks,

@CholoTook The library is a wrapper around the OPS API, and the difficulty at present is that there is no tutorial or examples scripts to showcase the different methods and responses. So you'll have to refer back to the OPS reference guide most of the time. Perhaps you want to open a discussion item on a specific topic or an issue, whichever you think is appropriate?