[gdal-dev] gdal-utils: About GDAL Python Utilities

Wed Feb 2 11:57:14 PST 2022

I revised according to your feedback and created an RST document from it. I’m not too experienced with the syntax so there may be some changes needed. Here’s the PR:
https://github.com/OSGeo/gdal/pull/5222

-Matt

From: Idan Miara <idan at miara.com>
Sent: February 1, 2022 12:30 PM
To: Matt.Wilkie <Matt.Wilkie at yukon.ca>
Cc: gdal-dev at lists.osgeo.org
Subject: Re: [gdal-dev] gdal-utils: About GDAL Python Utilities

*** External email: Do not click on links or attachments except from trusted senders. ***

******************************************************************************************

Hi Matt,

Thanks for looking into this.

Yes, you got it right.
You can find some documentation in the following pages, though it certainly could be approved as per your suggestions, maybe also by using some text from the RFC.
https://gdal.org/api/index.html#python-api
https://gdal.org/programs/index.html#programs (note the programs that end with .py)
https://gdal.org/api/python_samples.html
These doc pages are auto generated from the sources here:
https://github.com/OSGeo/gdal/tree/master/doc/source

> Osgeo_utils doesn’t have a top level document yet.
I'm not sure what you mean by a top level document (it doesn't have its own separate repository if that is what you meant).

>  It’s code root is .../swig/python/gdal-utils/osgeo_utils<https://github.com/OSGeo/gdal/tree/master/swig/python/gdal-utils/osgeo_utils> . It is nested inside the gdal-utils project. In your IDE set gdal-utils as the root folder. (not sure about this. Is it better to have osgeo_utils as root?)
In order to make python use the package without installing it you need to add its parent folder (that is  .../swig/python/gdal-utils/<https://github.com/OSGeo/gdal/tree/master/swig/python/gdal-utils/osgeo_utils> ) as a source dir), which practically inserts that folder at the top of your `sys.path`, which is where python looks for packages when you import. So because your `site-packages` folder is in your `sys.path` by default, then any package under it is recognized.
When you insert any other folder before it then it gets a higher priority (and that is what happens when you mark as source dir).

> Contribute changes with Pull Requests<https://github.com/OSGeo/gdal/pulls> from your fork to the main GDAL project (and use gdal-utils label?)
Right, A dedicated label sounds like a good idea.

Please feel free to make a PR to improve the above docs by editing the RST pages (https://github.com/OSGeo/gdal/tree/master/doc/source).
Feel free to ask further questions.

Idan.

On Tue, 1 Feb 2022 at 20:51, <Matt.Wilkie at yukon.ca<mailto:Matt.Wilkie at yukon.ca>> wrote:
Hi,

I had to read through RFC 78: gdal-utils package<https://gdal.org/development/rfc/rfc78_gdal_utils_package.html> a few times to wrap my head around what the major components are. Here’s some writing of what I think I understand. Is it correct?

About GDAL Python Utilities

The GDAL python utilities are included with GDAL. If you’ve installed GDAL you already have them. However you may want to use a newer or older version of the utilities without changing GDAL. This is where gdal-utils comes in.

gdal-utils: is the Gdal Python Utilities distribution. This is what you install. It’s home page is https://pypi.org/project/gdal-utils/ . Install it with `pip install gdal-utils` and it will up or downgrade the utilities in place.

osgeo_utils: is the python package. This is what you use in your code after installing, e.g. `from osgeo_utils import ...`. If you’re not writing code, ignore it.

(something here, perhaps names links to the utilities that are available on command line)

Developers

Clone or download the gdal project: https://github.com/OSGeo/gdal/

Osgeo_utils doesn’t have a top level document yet. It’s code root is .../swig/python/gdal-utils/osgeo_utils<https://github.com/OSGeo/gdal/tree/master/swig/python/gdal-utils/osgeo_utils> . It is nested inside the gdal-utils project. In your IDE set gdal-utils as the root folder.

(not sure about this. Is better to have osgeo_utils as root?)

Discuss via gdal-dev mailing list<https://lists.osgeo.org/mailman/listinfo/gdal-dev>.

Contribute changes with Pull Requests<https://github.com/OSGeo/gdal/pulls> from your fork to main GDAL project (and use gdal-utils label?)

Perhaps this could serve as part of a ‘gdal-utils’ project intro page somewhere. I think I still have write permissions to the Trac Wiki, but is that doesn’t feel like the right place to me.

(BW, the Nabble archive links are broken on the RFC page.)

Matt Wilkie
Geomatics Developer & Administrator
Environment | Technology, Innovation and Mapping
T 867-667-8133 | Yukon.ca<http://yukon.ca/>
Hours: 08:30-16:30, Mon-Wed: Office, Thu: Remote, Fri: Away.

_______________________________________________
gdal-dev mailing list
gdal-dev at lists.osgeo.org<mailto:gdal-dev at lists.osgeo.org>
https://lists.osgeo.org/mailman/listinfo/gdal-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/gdal-dev/attachments/20220202/bc1cb110/attachment-0001.html>