CLI: add --version long argument to return PROJ version

[lbartoletti]

The proposed --version option will enable users to easily retrieve the application's version without having to refer to documentation or resort to external means. This feature is essential for testing various behaviors and fulfilling a specific user requirement.

I have tried to adhere to the existing code conventions while implementing this feature. As of now, the changes have been applied only to one utility, but if it's OK, I'll extend the same modifications to other apps.

cc @Guts

• Closes Add --version CLI arg to all commands (e.g., proj, projsync, etc.) #3980, Add --version #2640
• Tests added
• Added clear title that can be used to generate release notes
• Fully documented, including updating docs/source/*.rst for new API

[kbevers]

I think this is a good idea. Can you please include an example here? Also, remember to adjust the docs as well so that this feature isn't a secret.

[rouault]

The gie and cct utilities already implement --version with the following output:

$ bin/gie --version
gie: Rel. 9.3.0, September 1st, 2023
$ bin/cct --version
cct: Rel. 9.3.0, September 1st, 2023

I guess with your proposed change, you'd reduce this to 9.3.0
I don't think that change would be critically breaking. Perhaps @busstoptaktik has an opinion regarding this

You could also change proj_info() in src/4D_api.cpp to change "info.version = version;" to "info.version = pj_get_version()"

[kbevers]

I wouldn't mind it if the date disappeared from the --version outputs of the apps. It's an annoying thing to maintain in releases.

[rouault]

It's an annoying thing to maintain in releases.

proj_info() reports 2 fields ".version=X.Y.Z" and ".release=Rel. X.Y.Z, date"

[Guts]

Thanks @lbartoletti!

To give context, I need to identify the installed PROJ version to adapt some parts of my logic. After some research, I've ended on this:

import re
import subprocess

proj_output = check_output(["proj"], stderr=STDOUT, text=True)
version_match = re.search(r"Rel\. ([0-9.]+)", proj_output):
if version_match:
    print(version_match.group(1))

But I did not know cie and cct!

See also:

• thread on Mastodon
• article on geotribu (preview) 🇫🇷

[busstoptaktik]

Perhaps @busstoptaktik has an opinion regarding this

@rouault this is one of the few things I cannot talk myself into having an opinion of 🙂 - but thanks for pinging me on the subject!

[snowman2]

There are quite a few implementations for this depending on the program. One option to consider could be to provide a simple version (easier to parse for the use case of this PR) and a more verbose version like Python does.

$ python --version
Python 3.10.10
$ python -V
Python 3.10.10
$ python -VV
Python 3.10.10 | packaged by conda-forge | (main, Mar 24 2023, 20:08:06) [GCC 11.3.0]

[snowman2]

Side note:

$ proj

Rel. 9.1.1, December 1st, 2022
usage: proj [-bdeEfiIlmorsStTvVwW [args]] [+opt[=arg] ...] [file ...]

[snowman2]

Code pyproj uses to get the proj version.

[jmckenna]

This is so needed, thank-you @lbartoletti for pushing this.

[jmckenna]

(initially reported at #2640 )

[lbartoletti]

There are quite a few implementations for this depending on the program. One option to consider could be to provide a simple version (easier to parse for the use case of this PR) and a more verbose version like Python does.

$ python --version
Python 3.10.10
$ python -V
Python 3.10.10
$ python -VV
Python 3.10.10 | packaged by conda-forge | (main, Mar 24 2023, 20:08:06) [GCC 11.3.0]

Indeed, my_soft --version should return my_soft X.Y.Z and not only X.Y.Z. Long version, could the actual one aka pg_get_release() : app_name: Rel. 9.3.0, September 1st, 2023

However, in our case, -VV is not possible, since it's used for verbosity in proj app.

May I suggest:

• app_name --version: app_name X.Y.Z, so proj --version: proj 9.3.0
• app_name --release (or --long-version?): app_name: Rel. 9.3.0, September 1st, 2023
• app_name --short-version (or --version-number? --version-semver?): 9.3.0

[rouault]

Personally, I would just stick with below for the sake of simplicity (most more popular utilities than the PROJ ones have just --version, so it might be over-engineered to offer 3 variants for PROJ...):

• app_name --version: app_name X.Y.Z, so proj --version: proj 9.3.0

The long version with the release date doesn't bring that much, given the release date is something that is a 1:1 match with the version number.

[jmckenna]

As a packager, this release date causes confusion to users (the date is often in the future, which causes confusion for the user, and grief for the packager). It would be good to not include this, in any utility.

[kbevers]

It would be good to not include this, in any utility.

Can someone give an educated guess as to what the impact of changing the output of cct --version and gie --version is? Have people been relying on these two to get the version number in a simpler way than using proj? If we think a limited number of users rely on this I am happy to change it but we shouldn't do it if it forces a lot of people to change existing workflows.

[github-actions]

The PROJ project highly values your contribution and would love to see this work merged! Unfortunately this PR has not had any activity in the last two months and is being automatically marked as "stale". If you think this pull request should be merged, please check

• that all unit tests are passing

• that all comments by reviewers have been addressed

• that there is enough information for reviewers, in particular

  • link to any issues which this pull request fixes

  • add a description of workflows which this pull request fixes

  • add terminal output examples if applicable

• that you have written unit tests where possible
  In case you should have any uncertainty, please leave a comment and we will be happy to help you proceed with this pull request.
  If there is no further activity on this pull request, it will be closed in a week.

[lbartoletti]

Not staled

[github-actions]

The PROJ project highly values your contribution and would love to see this work merged! Unfortunately this PR has not had any activity in the last two months and is being automatically marked as "stale". If you think this pull request should be merged, please check

• that all unit tests are passing

• that all comments by reviewers have been addressed

• that there is enough information for reviewers, in particular

  • link to any issues which this pull request fixes

  • add a description of workflows which this pull request fixes

  • add terminal output examples if applicable

• that you have written unit tests where possible
  In case you should have any uncertainty, please leave a comment and we will be happy to help you proceed with this pull request.
  If there is no further activity on this pull request, it will be closed in a week.

[github-actions]

While we hate to see this happen, this PR has been automatically closed because it has not had any activity in the last 2 months. If this pull request should be reconsidered, please follow the guidelines in the previous comment and reopen this pull request. Or, if you have any further questions, just ask! We love to help, and if there's anything the PROJ project can do to help push this PR forward please let us know how we can assist.

[Guts]

Still interested in this feature and homogenization work.

[kbevers]

I agree that this is a sane and useful change but since I haven't received any feedback to this

Can someone give an educated guess as to what the impact of changing the output of cct --version and gie --version is? Have people been relying on these two to get the version number in a simpler way than using proj? If we think a limited number of users rely on this I am happy to change it but we shouldn't do it if it forces a lot of people to change existing workflows.

I can't really make a decision on how to proceed. For now I am inclined to not merge this PR and instead streamline the version options of the various CLI utilities in a future 10.0 release.

[jmckenna]

@kbevers can you leave this PR open and possibly add a label to it of "10.0 release" ? I am sure that @lbartoletti can adapt the changes to anything that you need for 10.0

Thanks for all of this effort @lbartoletti, it is very useful to the community.

[DeflateAwning]

Well that's funny. Just opened a feature request issue for this exact feature. Happy to see it's implemented!

Fixes #3980