Package: robotpajamas.pants.scie
pants-scie-pluginThis plugin provides ascie_binarytarget that can be used to create a single-file Python executable with an embedded Python interpreter, built viascie-jump.It usesscienceand a.tomlconfiguration file to build the executable, expecting apex_binaryas a dependency.InstallationThis plugin was developed using Python 3.9 and Pants 2.16.0.rc3, but should work with Pants 2.15+ (however, your mileage may vary).Add the following to yourpants.tomlfile:[GLOBAL]plugins=[..."robotpajamas.pants.scie",]...backend_packages=[..."experimental.scie",]UsageAt the moment, thescie_binaryexpects apex_binaryas its only dependency. There is no technical limitation to this, but it simplified the initial implementation.For trivial packaging, you can set anentry_pointon yourpex_binaryand thescie_binarywill directly call your pex (e.g.python myapp.pex). This can be particularly useful for CLIs or other simple applications. The name of your binary will be the name of yourscie_binarytarget, and it will be placed in thedistdirectory.# BUILDpex_binary(name="mycli-pex",entry_point="mycli.main",...)scie_binary(name="mycli",dependencies=[":mycli-pex"],...)You can optionally cross-build your executable by setting theplatformsfield on yourscie_binarytarget. This will create a binary for the specified platform, and will be named accordingly (e.g.mycli-linux-x86_64). You should also ensure that yourpex_binaryis built for the same platform(s).# BUILDpex_binary(name="mycli-pex",entry_point="mycli.main",platforms=["linux-x86_64-cp-311-cp311","macosx-13.3-arm64-cp-311-cp311",]...)scie_binary(name="mycli",dependencies=[":mycli-pex"],platforms=["linux-x86_64","macos-aarch64",]...)Advanced UsageFor non-trivial packaging, it is much easier (and cleaner) to use thescienceconfig TOML file to specify what should be in the package and how it should work. This may be in situations where you want multiple commands, or you require boot bindings. A good example of this is setting up a FastAPI application with a Uvicorn or Gunicorn runner, which requires using PEX_TOOLS and creating avenvfrom your code.The plugin will attempt to replace variables in the TOML with equivalent ones specified in the target. For example, the binary name, the binary description,platforms(if specified), etc... The one critical aspect to note is that in order to reference another target (e.g. the output ofpex_binary), use the:target_namesyntax in the TOML. The plugin will usescience's--filemapping argument to replace the target name with the actual file path.# BUILDpex_binary(name="hellofastapi-pex",entry_point="hellofastapi.main",dependencies=[":libhellofastapi"],include_tools=True,)scie_binary(name="hellofastapi",dependencies=[":hellofastapi-pex"],lift="lift.toml",...)# lift.toml[lift]name="hellofastapi"description="An example FastAPI Lift application including using an external uvicorn server"[[lift.interpreters]]id="cpython"provider="PythonBuildStandalone"release="20230507"version="3.11.3"[[lift.files]]# Note the leading colon, which is required to reference the pex_binary dependencyname=":hellofastapi-pex"[[lift.commands]]exe="{scie.bindings.venv}/venv/bin/uvicorn"args=["hellofastapi.main:app","--port","7999"]description="The FastAPI executable."[[lift.bindings]]name="venv"description="Installs HelloFastAPI into a venv and pre-compiles .pyc"exe="#{cpython:python}"args=["{:hellofastapi-pex}","venv","--bin-path","prepend","--compile","--rm","all","{scie.bindings}/venv",][lift.bindings.env.default]"=PATH"="{cpython}/python/bin:{scie.env.PATH}""PEX_TOOLS"="1""PEX_ROOT"="{scie.bindings}/pex_root"