Main Content

compiler.build.pythonPackage

Create Python package for deployment outside MATLAB

    Description

    example

    compiler.build.pythonPackage(FunctionFiles) creates a Python® package using the MATLAB® functions specified by FunctionFiles.

    example

    compiler.build.pythonPackage(FunctionFiles,Name,Value) creates a Python package with additional options specified using one or more name-value arguments. Options include the package name, output directory, and additional files to include.

    example

    compiler.build.pythonPackage(opts) creates a Python package with options specified using a compiler.build.PythonPackageOptions object opts. You cannot specify any other options using name-value arguments.

    example

    results = compiler.build.pythonPackage(___) returns build information as a compiler.build.Results object using any of the input argument combinations in previous syntaxes. The build information consists of the build type, paths to the compiled files, and build options.

    Examples

    collapse all

    Create a Python package using a function file that generates a magic square.

    In MATLAB, locate the MATLAB function that you want to deploy as a Python package. For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler.

    appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');

    Build a Python package using the compiler.build.pythonPackage command.

    compiler.build.pythonPackage(appFile);

    The build function creates the following files within a folder named magicsquarepythonPackage in your current working directory:

    • GettingStarted.html

    • example

    • mccExcludedFiles.log

    • readme.txt

    • requiredMCRProducts.txt

    • setup.py

    • unresolvedSymbols.txt

    Create a Python package and customize it using name-value arguments.

    For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler.

    appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');

    Build a Python package using the compiler.build.pythonPackage command. Use name-value arguments to specify the package name, add a MAT-file, and enable verbose output.

    compiler.build.pythonPackage(appFile,'PackageName','MyMagicSquare',...
        'AdditionalFiles','myvars.mat',...
        'Verbose','on');

    Create multiple Python packages using a compiler.build.PythonPackageOptions object.

    For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler.

    appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');

    Create a PythonPackageOptions object using appFile. Use name-value arguments to specify a common output directory, disable automatic detection of data files, and enable verbose output.

    opts = compiler.build.PythonPackageOptions(appFile,...
        'OutputDir','D:\Documents\MATLAB\work\PythonPackageBatch',...
        'AutoDetectDataFiles','off',...
        'Verbose','on')
    opts =
    
      PythonPackageOptions with properties:
    
                FunctionFiles: {'C:\Program Files\MATLAB\R2021a\extern\examples\compiler\magicsquare.m'}
        SampleGenerationFiles: {}
              AdditionalFiles: {}
          AutoDetectDataFiles: off
                      Verbose: on
                    OutputDir: 'D:\Documents\MATLAB\work\PythonPackageBatch'

    Build the Python package using the PythonPackageOptions object.

    compiler.build.pythonPackage(opts);

    To compile using the function file myMagic2.m with the same options, use dot notation to modify the FunctionFiles argument of the existing PythonPackageOptions object before running the build function again.

    opts.FunctionFiles = 'myMagic2.m';
    compiler.build.pythonPackage(opts);

    By modifying the FunctionFiles argument and recompiling, you can compile multiple components using the same options object.

    Create a Python package and save information about the build type, generated files, and build options to a compiler.build.Results object.

    Compile using the file magicsquare.m located in matlabroot\extern\examples\compiler.

    results = compiler.build.pythonPackage('magicsquare.m');
    results = 
    
      Results with properties:
    
                BuildType: 'pythonPackage'
                    Files: {3×1 cell}
                  Options: [1×1 compiler.build.PythonPackageOptions]

    The Files property contains the paths to the following:

    • example folder

    • setup.py

    • GettingStarted.html

    Input Arguments

    collapse all

    Files implementing MATLAB functions, specified as a character vector, a string scalar, a string array, or a cell array of character vectors. File paths can be relative to the current working directory or absolute. Files must have a .m extension.

    Example: ["myfunc1.m","myfunc2.m"]

    Data Types: char | string | cell

    Python package build options, specified as a compiler.build.PythonPackageOptions object.

    Name-Value Pair Arguments

    Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

    Example: 'Verbose','on'

    Additional files to include in the Python package, specified as a character vector, a string scalar, a string array, or a cell array of character vectors. File paths can be relative to the current working directory or absolute.

    Example: 'AdditionalFiles',["myvars.mat","data.txt"]

    Data Types: char | string | cell

    Flag to automatically include data files, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    • If you set this property to 'on', then data files that you provide as inputs to certain functions (such as load and fopen) are automatically included in the package.

    • If you set this property to 'off', then you must add data files to the package using the AdditionalFiles option.

    Example: 'AutoDetectDataFiles','off'

    Data Types: logical

    Name of the Python package, specified as a character vector or a string scalar. Specify 'PackageName' as a namespace, which is a period-separated list, such as companyname.groupname.component. The name of the generated package is set to the last entry of the period-separated list. The name must begin with a letter and contain only alphabetic characters and periods.

    Example: 'PackageName','mathworks.pythonpackage.mymagic'

    Data Types: char | string

    MATLAB sample files used to generate sample Python files for functions included with the package, specified as a character vector, a string scalar, a string array, or a cell array of character vectors. File paths can be relative to the current working directory or absolute. Files must have a .m extension.

    Example: 'SampleGenerationFiles',["sample1.m","sample2.m"]

    Data Types: char | string | cell

    Path to the output directory where the build files are saved, specified as a character vector or a string scalar. The path can be relative to the current working directory or absolute.

    The default name of the build folder is the package name appended with pythonPackage.

    Example: 'OutputDir','D:\Documents\MATLAB\work\mymagicpythonPackage'

    Data Types: char | string

    Flag to control build verbosity, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    • If you set this property to 'on', then the MATLAB command window displays progress information indicating compiler output during the build process.

    • If you set this property to 'off', then the command window does not display progress information.

    Example: 'Verbose','on'

    Data Types: logical

    Output Arguments

    collapse all

    Build results, returned as a compiler.build.Results object. The Results object contains:

    • Build type, which is 'pythonPackage'

    • Paths to the following items:

      • example folder

      • setup.py

      • GettingStarted.html

    • Build options, specified as a PythonPackageOptions object

    Introduced in R2021a