Document existing public API for bw2projects

[baali]

We want to isolate projects into separate library. For that we have to document:

• Existing public APIs for projects that are being used in bw2data
• Identify the APIs that don't belong to bw2projects but is part of existing projects and should be removed
• Identify future APIs that should be supported by bw2projects

related to brightway-lca/brightway2-data#98

[baali]

• Existing public APIs for projects that are being used in bw2data

Most of the time in bw2data, we are using projects to access directory. Here is list of files and methods being called on projects

1. backends/__init__.py: projects.dir / "lci" / "databases.db",
2. backends/base.py: return projects.dir / "processed",
3. compat.py: check around brigitway 2.5 version
4. data_store.py: filepath = projects.dir / self._intermediate_dir / (self.filename + ".pickle")
return projects.dir / "processed"
filepath = projects.dir / self._intermediate_dir / (self.filename + ".pickle")
5. logs.py:
   projects.logs_dir / filename,
zip_fo = create_in_memory_zipfile_from_directory(projects.logs_dir)
6. parameters.py: projects.dir / "parameters.db",
7. search/indices.py: self.path = os.path.join(projects.request_directory("whoosh"), database_path)
8. serailization.py: self.filepath = (maybe_path(dirpath) or projects.dir) / self.filename
9. updates.py:
   shutil.rmtree(projects.request_directory("whoosh"))
processed_dir = projects.dir / "processed"
projects.request_directory("migrations")
10. utils.py

[cmutel]

Great! In the end, this should be relatively easy, as there is really only .dir, .logs_dir, and .request_directory(). We can deprecate .request_directory(), with a message to use pathlib.Path.mkdir(exist_ok=True). The .dir and .logs_dir should be instances of pathlib.Path.

BTW, you probably also know this, but we are using appdirs for cross-platform directory locations. I would be ok to switch to using .user_data_dir and .user_log_dir (with backwards compatibility shims) to be consistent with that library.

Not sure this is the best path, but what I had in mind for bw2data was something like a test import of bw_projects, and if that failed there would be a singleton which had the same API but required environment variables to set the base path (other it could use cwd).

[baali]

• Identify future APIs that should be supported by bw2projects

In the end, this should be relatively easy, as there is really only .dir, .logs_dir, and .request_directory(). We can deprecate .request_directory(), with a message to use pathlib.Path.mkdir(exist_ok=True). The .dir and .logs_dir should be instances of pathlib.Path.

[baali]

Further including comments from our conversation to keep a record here also:

projects is a proxy to folders where SQliteDB files are stored. That sounds straightforward. But projects is also responsible for migrations, generating report, doing automatic_updates, they sound more like bw2data methods.

anything to do with migrations or automatic_updates (these are the same thing) should stay with bw2data. I guess the simplest thing there would be to do the same as with the preferences, store the information in a SQLite table, and check if updates are needed on first import. I could imagine a hook that bw_projects would call in bw2data, but I previously thought that this was too much dependency. Now I am not sure.