Add HOWTO + FAQ on file management

[freakboy3742]

What is the problem or limitation you are having?

Discord and Discussions frequently include questions about how to access and store files in a running app. The advice is almost always the same - pointing at the app.paths documentation.

Describe the solution you'd like

We should add:

1. A HOWTO document on managing files.
2. A FAQ that points to the HOWTO.

Describe alternatives you've considered

n/a

Additional context

@rmartin16 recently provided a good model answer that could be used as the start of a draft. It uses a database as a use case.

---

This is a common idiom in BeeWare apps: shipping an app with a seeded database to be updated by the user after installation.

In this case, you include such a database (or csv file in this case) alongside your source code; storing this database in a resources directory would make sense.

Now, at runtime, this database is available at the App's installation file path. If you're using Toga, you can use the toga.paths.Paths API to access useful file system locations; for instance, the app's installation file path is available via toga.paths.Paths().app. More simply, this same path is available via your toga.App subclass at self.paths.app. Therefore, you can access your database via self.paths.app / "resources/db.csv" at runtime.

Since it is not safe to assume the app's installation location is writable, you should copy the seeded database to a known-writable location. For this, you should use self.paths.data as a safe and persistent location to store user data.

So, all put together, you add this to your app's startup() function...and youre good to go:

class HelloWorld(toga.App):
    def startup(self):
        self.db_filepath = self.paths.data / "app.db"
        if not self.db_filepath.exists():
            self.db_filepath.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy(self.paths.app / f"resources/{self.db_filepath.name}", self.db_filepath)

---

[kattni]

The how-to is completed.

Can you please clarify what you're expecting with regard to wording for the FAQ?

[freakboy3742]

A FAQ should be phrased in terms of how the question manifests in practice - so I’d suggest there’s probably 2 FAQs here.

The first is something like “How do I open files with Toga?”, with an answer that points out that Toga is standard Python, so any Python file operations (including open, and libraries like json and tomllib) will work.

The second is something like “Why can’t my Toga app find my files?”, with a short summary answer highlighting that the problem is absolute vs relative paths, pointing at the HOWTO.

[freakboy3742]

This was resolved by #3552.

[kattni]

@freakboy3742 The FAQ has not been added. I have it on my list, but this issue isn't entirely completed as it stands.

[freakboy3742]

Ah - apologies. Reopening on that basis.