What is the recommended/ideal way to do python-to-python imports?

[quaris628]

Importing a python file to a mast file is pretty straightforward: import file_name.py (assuming they're in __init__.py already)
But importing py to py seems trickier (apart from the sbs library).

I've figured out that this works:
from data.missions.mission_name.optional_subfolder_name.file_name import function_name_1
But I don't like how fragile this makes the name of the mission folder; if someone renames it, the code breaks, which isn't very intuitive.

Is there a better way?

[dougreichard]

It is highly recommended to only import python files in the same folder to allow the folder to be bundled as an add on.

from . import other.py
# or 
from .other import my_func

(Note: I haven't tried any of the following. but it would be the intended method)

This may require a _init_.py which can be empty for python to recognize it or the python file may need to be ordered correctly in the _init_.mast.

If this is in a standalone mission that is not intended to use folders as packaged addons, then you may have the python in a folder. Make sure the folder has a _init_.py (instead of or including a _init_.mast

With this is in place it may work to:

from ..my_py_files.stuff import my_function_two

If you intend this to be part of a module/addon for use in other missions it should be packaged as a sbslib and dependent missions should place it in the proper section in story.json.

The folder could be zipped up into a file and use the sbslib extension. An sbslib should have no MAST files.
Packaging the sbslib is up to the scripter to create, but would be similar to the build_addons in legendary missions for packaging mastlib files.

[quaris628]

With guidance/instructions from astrolamb (thank you!), I figured out how to use sbslib and mastlib files, which is what I'm doing for the specific use case that made me ask this question.

Your note about the order of the imports in __init__.mast seems to be what I was doing wrong. With the dependent listed prior to the dependee, the from file_name import function_name and import file_name syntax is working!

Unfortunately, apart from the __init__.mast ordering, either I'm misunderstanding something in your non-sbslib instructions or they don't work as written. from . import file_name.py causes an "Exception: invalid syntax". Both from .file_name import function_name and from ..file_name import function_name (with the file_name file positioned accordingly) causes an "Exception: attempted relative import with no known parent package". But I think I have what I need now, so this is mainly an FYI, and an explanation for why I'd rather not mark this as the accepted answer.

[quaris628]

The normal import file_name and from file_name import function_name syntax will work as long as:

1. file_name.py is in the same folder as the file you're adding the import statement to
2. Both files are listed in __init__.mast
3. In __init__.mast, file_name.py is listed prior to the the file you're adding the import statement to

Condition 3 is what tripped me up.

If you have code that need to be referenced by multiple other files in folders you want to keep as independent add-ons, it's recommended to put the shared code in an sbslib (or mastlib) that they can reference. Edit: I disagree with this recommendation; see below comment

[quaris628]

So after ~4 months of working with mastlibs, I've come to believe that they cause more problems than they solve. If anyone reading this has code that needs to be referenced from multiple subfolders, I instead recommend using absolute imports (as described in my original post), despite that solution having its own shortcomings.

The problems with using mastlibs/sbslibs are...

• You have to zip them up every time you update the code contained within. Which is...
  • Easy to forget to do before you restart the mission
  • Slow to do manually every time, which is especially impactful when you want to iterate quickly on code inside a mastlib
  • A significant investment to automate with a separate script. There are some examples in the vanilla game files, but they're narrowly tailored/tightly coupled to the legendary missions use case, i.e. are hard to reuse, so I ended up just rewriting my scripts for this from the ground up.
• They are unreadable and therefore unmergeable by version control systems
• The zipped binary is nondeterministic from solely the contents of the zipped files. This makes it harder to know whether the mastlib is up to date and needs to be regenerated or not, along with making various version control workflows such as resolving merge conflicts more tedious.

The problems with using absolute imports are...

• Code breaks if the mission folder name is changed. (But it's not too hard to find and replace all instances of the name...)

[dougreichard]

Yes, as the marked answer describes

If the python file is imported in _init_.mast it will be a python module which is why and how the answer works internally.
I forgot that aspect in my original response.