.. _global_options:

Global Options Object
=====================

.. module:: ezdxf.options

The global `ezdxf` options are stored in the object :mod:`ezdxf.options`.

Recommended usage of the global :attr:`options` object::

    import ezdxf

    value = ezdxf.options.attribute

.. important::

    Most options are only read at startup (support folders, paths to executables),
    changing these values has no effect at runtime. To change these options, you must
    create a configuration file, see section :ref:`config_files`.

The :attr:`options` object uses the Standard Python class :class:`ConfigParser`
to manage the configuration. Shortcut attributes like :attr:`test_files` are
simple properties and most shortcuts are read only marked by (Read only),
read and writeable attributes are marked by (Read/Write).

To change options, especially the read only attributes, you have to edit the
config file with a text editor, or set options by the :meth:`set` method and
write the current configuration into a config file.

.. _config_files:

Config Files
============

The default config files are loaded from the user home directory as
"~/.config/ezdxf/ezdxf.ini", and the current working directory as "./ezdxf.ini".
A custom config file can be specified  by the environment variable
``EZDXF_CONFIG_FILE``. Ezdxf follows the `XDG Base Directory specification`_
if the environment variable ``XDG_CONFIG_HOME`` is set.

The config file loading order:

1. user home directory: "~/.config/ezdxf/ezdxf.ini"
2. current working directory: "./ezdxf.ini"
3. config file specified by ``EZDXF_CONFIG_FILE``

A configuration file that is loaded later does not replace the previously loaded
ones, only the existing options in the newly loaded file are added to the
configuration and can overwrite existing options.

.. _config_file:

Configuration files are regular INI files, managed by the standard Python
`ConfigParser`_ class.

File Structure:

.. code:: INI

    [core]
    default_dimension_text_style = OpenSansCondensed-Light
    test_files = D:\Source\dxftest
    support_dirs =
        "C:\Program Files\Bricsys\BricsCAD V23 en_US\Fonts",
        "~/dir2",
        "~/dir3",
    load_proxy_graphics = true
    store_proxy_graphics = true
    log_unprocessed_tags = false
    filter_invalid_xdata_group_codes = true
    write_fixed_meta_data_for_testing = false
    disable_c_ext = false

    [browse-command]
    text_editor = "C:\Program Files\Notepad++\notepad++.exe" "{filename}" -n{num}

Modify and Save Changes
-----------------------

This code shows how to get and set values of the underlying :class:`ConfigParser`
object, but use the shortcut attributes if available:

.. code-block:: Python

    # Set options, value has to ba a str, use "true"/"false" for boolean values
    ezdxf.options.set(section, key, value)

    # Get option as string
    value = ezdxf.options.get(section, key, default="")

    # Special getter for boolean, int and float
    value = ezdxf.options.get_bool(section, key, default=False)
    value = ezdxf.options.get_int(section, key, default=0)
    value = ezdxf.options.get_float(section, key, default=0.0)

If you set options, they are not stored automatically in a config file, you have
to write back the config file manually:

.. code-block:: Python

    # write back the default user config file "ezdxf.ini" in the
    # user home directory
    ezdxf.options.write_home_config()

    # write back to the default config file "ezdxf.ini" in the
    # current working directory
    ezdxf.options.write_file()

    # write back to a specific config file
    ezdxf.options.write_file("my_config.ini")
    # which has to be loaded manually at startup
    ezdxf.options.read_file("my_config.ini")

This example shows how to change the :attr:`test_files` path and save the
changes into a custom config file "my_config.ini":

.. code-block:: Python

    import ezdxf

    test_files = Path("~/my-dxf-test-files").expand_user()
    ezdxf.options.set(
        ezdxf.options.CORE,  # section
        "test_files",  # key
        "~/my-dxf-test-files",  # value
    )
    ezdxf.options.write_file("my_config.ini")

.. _use_a_custom_config_file:

Use a Custom Config File
------------------------

You can specify a config file by the environment variable
``EZDXF_CONFIG_FILE``, which is loaded after the default config files.

.. code-block:: Text

    C:\> set EZDXF_CONFIG_FILE=D:\user\path\custom.ini

Custom config files are not loaded automatically like the default config files.

This example shows how to load the previous created custom config file
"my_config.ini" from the current working directory:

.. code-block:: Python

    import ezdxf

    ezdxf.options.read("my_config.ini")

That is all and because this is the last loaded config file, it overrides all
default config files and the config file specified by ``EZDXF_CONFIG_FILE``.

Functions
---------

.. function:: set(section: str, key: str, value: str)

    Set option `key` in `section` to `values` as ``str``.

.. function:: get(section: str, key: str, default: str = "") -> str

    Get option `key` in `section` as string.

.. function:: get_bool(section: str, key: str, default: bool = False) -> bool

    Get option `key` in `section` as ``bool``.

.. function:: get_int(section: str, key: str, default: int = 0) -> int

    Get option `key` in `section` as ``int``.

.. function:: get_float(section: str, key: str, default: float = 0.0) -> flot

    Get option `key` in `section` as ``float``.

.. function:: write(fp: TextIO)

    Write configuration into given file object `fp`, the file object
    must be a writeable text file with "utf8" encoding.

.. function:: write_file(filename: str = "ezdxf.ini")

    Write current configuration into file `filename`, default is "ezdxf.ini" in
    the current working directory.

.. function:: write_home_config()

    Write configuration into file "~/.config/ezdxf/ezdxf.ini",
    ``$XDG_CONFIG_HOME`` is supported if set.

.. function:: read_file(filename: str)

    Append content from config file `filename`, but does not reset the
    configuration.

.. function:: print()

    Print configuration to `stdout`.

.. function:: reset()

    Reset options to factory default values.

.. function:: delete_default_config_files()

    Delete the default config files "ezdxf.ini" in the current working and in
    the user home directory "~/.config/ezdxf", ``$XDG_CONFIG_HOME`` is supported
    if set.

.. function:: preserve_proxy_graphics(state=True)

    Enable/disable proxy graphic load/store support by setting the
    options ``load_proxy_graphics`` and ``store_proxy_graphics`` to `state`.

.. attribute:: loaded_config_files

    Read only property of loaded config files as tuple for :class:`Path`
    objects.

Core Options
------------

For all core options the section name is ``core``.


Default Dimension Text Style
++++++++++++++++++++++++++++

The default dimension text style is used by the DIMENSION renderer of `ezdxf`,
if the specified text style exist in the STYLE table. To use any of the default
style of `ezdxf` you have to setup the styles at the creation of the DXF
document: :code:`ezdxf.new(setup=True)`, or setup the `ezdxf` default styles
for a loaded DXF document:

.. code-block:: Python

    import ezdxf
    from ezdxf.tool.standard import setup_drawing

    doc = ezdxf.readfile("your.dxf")
    setup_drawing(doc)

Config file key: ``default_dimension_text_style``

Shortcut attribute:

.. attribute:: default_dimension_text_style

    (Read/Write) Get/Set default text style for DIMENSION rendering, default
    value is ``OpenSansCondensed-Light``.

Load Proxy Graphic
++++++++++++++++++

Proxy graphics are not essential for DXF files, but they can provide a simple
graphical representation for complex entities, but extra memory is needed to
store this information. You can save some memory by not loading the proxy
graphic, but the proxy graphic is lost if you write back the DXF file.

The current version of `ezdxf` uses this proxy graphic to render MLEADER
entities by the :mod:`~ezdxf.addons.drawing` add-on.

Config file key: ``load_proxy_graphics``

Shortcut attribute:

.. attribute:: load_proxy_graphics

    (Read/Write) Load proxy graphics if ``True``, default is ``True``.

Store Proxy Graphic
+++++++++++++++++++

Prevent exporting proxy graphics if set to ``False``.

Config file key: ``store_proxy_graphics``

Shortcut attribute:

.. attribute:: store_proxy_graphics

    (Read/Write)  Export proxy graphics if ``True``, default is ``True``.

Support Directories
+++++++++++++++++++

Search directories for support files:

- plot style tables, the .ctb or .stb pen assignment files
- shape font files of type .shx or .shp or .lff

.. important::

    When you add new font directories to ``support_dirs`` or new fonts to one of the
    support directories, you have to rebuild the font cache to use these fonts,
    see section :ref:`Rebuilding the Font Cache` for more information.

Config file key: ``support_dirs``

Shortcut attribute:

.. attribute:: support_dirs

    (Read/Write) Search directories as list of strings.

Use quotes for paths including spaces:

.. code-block:: ini

    [core]
    support_dirs =
        ~/dir1,
        ~/dir2,
        "~/dir 3",

Debugging Options
-----------------

For all debugging options the section name is ``core``.

Test Files
++++++++++

Path to test files. Some of the `CADKit`_ test files are used by the
integration tests, these files should be located in the
:code:`ezdxf.options.test_files_path / "CADKitSamples"` folder.

Config file key: ``test_files``

Shortcut attributes:

.. attribute:: test_files

    (Read only) Returns the path to the `ezdxf` test files as ``str``,
    expands "~" construct automatically.

.. attribute:: test_files_path

    (Read only) Path to test files as :class:`pathlib.Path` object.


Filter Invalid XDATA Group Codes
++++++++++++++++++++++++++++++++

Only a very limited set of group codes is valid in the XDATA section and
AutoCAD is very picky about that. `Ezdxf` removes invalid XDATA group codes
if this option is set to ``True``, but this needs processing time, which is
wasted if you get your DXF files from trusted sources like AutoCAD or BricsCAD.

Config file key: ``filter_invalid_xdata_group_codes``

.. attribute:: filter_invalid_xdata_group_codes

    (Read only) Filter invalid XDATA group codes, default value is ``True``.

Log Unprocessed Tags
++++++++++++++++++++

Logs unprocessed DXF tags, this helps to find new and undocumented DXF features.

Config file key: ``log_unprocessed_tags``

.. attribute:: log_unprocessed_tags

    (Read/Write) Log unprocessed DXF tags for debugging, default value is
    ``False``.

Write Fixed Meta Data for Testing
+++++++++++++++++++++++++++++++++

Write the DXF files with fixed meta data to test your DXF files by a diff-like
command, this is necessary to get always the same meta data like the saving
time stored in the HEADER section. This may not work across different `ezdxf`
versions!

Config file key: ``write_fixed_meta_data_for_testing``

.. attribute:: write_fixed_meta_data_for_testing

    (Read/Write) Enable this option to always create same meta data for testing
    scenarios, e.g. to use a diff-like tool to compare DXF documents,
    default is ``False``.

Disable C-Extension
+++++++++++++++++++

It is possible to deactivate the optional C-extensions if there are any issues
with the C-extensions. This has to be done in a default config file or by
environment variable before the first import of `ezdxf`. For ``pypy3`` the
C-extensions are always disabled, because the JIT compiled Python code is
much faster.

.. important::

    This option works only in the **default config files**, user config files which
    are loaded by :func:`ezdxf.options.read_file()` cannot disable the C-Extensions,
    because at this point the setup process of `ezdxf` is already finished!

Config file key: ``disable_c_ext``

.. attribute:: disable_c_ext

    (Read only) This option disables the C-extensions if ``True``.
    This can only be done before the first import of `ezdxf` by using a config
    file or the environment variable ``EZDXF_DISABLE_C_EXT``.

Use C-Extensions
++++++++++++++++

.. attribute:: use_c_ext

    (Read only) Shows the actual state of C-extensions usage.

.. _environment_variables:

Environment Variables
=====================

Some feature can be controlled by environment variables. Command line example
for disabling the optional C-extensions on Windows::

    C:\> set EZDXF_DISABLE_C_EXT=1

.. important::

    If you change any environment variable, you have to restart
    the Python interpreter!

EZDXF_DISABLE_C_EXT
    Set environment variable ``EZDXF_DISABLE_C_EXT`` to ``1`` or ``True`` to
    disable the usage of the C-extensions.

EZDXF_TEST_FILES
    Path to the `ezdxf` test files required by some tests, for instance the
    `CADKit`_ sample files should be located in the
    ``EZDXF_TEST_FILES/CADKitSamples`` folder. See also option
    :attr:`ezdxf.options.test_files`.

EZDXF_CONFIG_FILE
    Specifies a user config file which will be loaded automatically after the
    default config files at the first import of `ezdxf`.

.. _CADKit: https://cadkit.blogspot.com/p/sample-dxf-files.html?view=magazine
.. _ConfigParser: https://docs.python.org/3/library/configparser.html
.. _XDG Base Directory specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html