search

ODM2 / ODM2PythonAPI

A set of Python functions that provides data read/write access to an ODM2 database by leveraging SQLAlchemy.
http://odm2.github.io/ODM2PythonAPI/
BSD 3-Clause "New" or "Revised" License
4 stars 13 forks source link

Reorganizing module hierarchy structure to remove ODM2 folder #146

Open emiliom opened 6 years ago

emiliom commented 6 years ago

We started discussing this some time ago at #135

@lsetiawan's PR #145 is intended to create a very nifty deprecation pathway to implement the reorganization and removal of the ODM2 folder.

Background discussions (copied from #135)

Emilio:

There's one issue that I think needs to be discussed soon, before odm2api can be seen as really stable. Currently the package has a packager/folder hierarchy that includes a now-useless "ODM2" folder: https://github.com/ODM2/ODM2PythonAPI/tree/master/odm2api/ODM2

That forces most module import statements to include the useless ODM2 package hierarchy (eg, odm2api.ODM2.services.readService). We'll need to get rid of the ODM2 folder hierarchy, and the sooner we do it the better, to minimize disruptions. I strongly recommend that we do it in the next release, giving ourselves plenty of time for all code that uses odm2api to make the adjustment.

Anthony:

I'm very much a fan of moving forward soon with the next release to remove the useless "ODM2" level of hierarchy (clipped unrelated comment). With release v0.7 minted as is, any software that depends on the old conventions still have handy access to that version, while we can move forward with migrating our actively developed stuff to our widespread conventions.

emiliom commented 6 years ago

@lsetiawan, a question about the sphinx documentation: what happens once we merge your PR #146 (assuming it does what we want), in terms of the API Sphinx documentation? Now there'll be two valid module paths, one with the ODM2 path/package component, one without. Can we choose which one to show in the API documentation?

For reference, here's the API doc for readService, which currently has the module path odm2api.ODM2.services.readService. The new path would be odm2api.services.readService, but the old one will still work.

lsetiawan commented 6 years ago

For the sphinx, I'd probably have to update the rst docs. See https://github.com/ODM2/ODM2PythonAPI/blob/master/docs/source/modules.rst. We would like to show the new ones correct? I'm not sure how the old one will render in the documentation. Thanks.

emiliom commented 6 years ago

For the sphinx, I'd probably have to update the rst docs.

Ok. So we control that. Cool.

We would like to show the new ones correct?

Exactly

lsetiawan commented 6 years ago

Done in #147. Closing.

emiliom commented 6 years ago

Thanks for closing.

I guess regarding the docs:

For the sphinx, I'd probably have to update the rst docs. See https://github.com/ODM2/ODM2PythonAPI/blob/master/docs/source/modules.rst. We would like to show the new ones correct? I'm not sure how the old one will render in the documentation.

The updates should be done only when issue a new release.

lsetiawan commented 6 years ago

I can update that now, so it will be included in the new release.

emiliom commented 6 years ago

I can update that now, so it will be included in the new release.

Great, thanks.

emiliom commented 6 years ago

I'm reopening this issue as a reminder that in a future release (date TBD), we'll remove support for the now-deprecated "ODM2" package module hierarchy. That, import statements such as this one:

odm2api.ODM2.services.readService

will eventually no longer be supported, and only the new hiearchy will be supported:

odm2api.services.readService
emiliom commented 5 years ago

Note to self: Make sure to read #159 for "definitive" findings about the preservation of git history after the module moves.