kigadgets.environment
=====================

.. py:module:: kigadgets.environment

.. autoapi-nested-parse::

   Automatic linker to pcbnew GUI and pcbnew python package
   Use this one time to create the link by running python -m kigadgets

   It will also symlink "kipython" for Mac users
   kipython refers to the python executable that ships with KiCad installation



Attributes
----------

.. autoapisummary::

   kigadgets.environment.pcbnew_path_store
   kigadgets.environment.startup_script
   kigadgets.environment.plugin_script
   kigadgets.environment.help_msg
   kigadgets.environment.parser


Functions
---------

.. autoapisummary::

   kigadgets.environment.get_pcbnew_path_from_file
   kigadgets.environment.get_pcbnew_path
   kigadgets.environment.get_pcbnew_module
   kigadgets.environment.latest_version_configpath
   kigadgets.environment.get_default_paths
   kigadgets.environment.populate_existing_default_paths
   kigadgets.environment.kipython_one_liner
   kigadgets.environment.get_ver
   kigadgets.environment.get_cfg_script
   kigadgets.environment.populate_optimal_paths
   kigadgets.environment.macwin_on_dlopen_error
   kigadgets.environment.input_preferred_PATH
   kigadgets.environment.symlink_kipython_executable
   kigadgets.environment.write_PyShell_startup_script
   kigadgets.environment.write_plugin_importer_script
   kigadgets.environment.create_link
   kigadgets.environment.cl_main
   kigadgets.environment.cl_geohash


Module Contents
---------------

.. py:data:: pcbnew_path_store

.. py:function:: get_pcbnew_path_from_file()

.. py:function:: get_pcbnew_path()

   Look for the real pcbnew.py from
       1. environment variable PCBNEW_PATH, then
       2. cached file ./.path_to_pcbnew_module
       3. default install locations (platform dependent)

   If none of these work, return None


.. py:function:: get_pcbnew_module(verbose=True)

   returns the imported module. Modifies sys.path so that
   subsequent "import pcbnew" will work as expected.


.. py:function:: latest_version_configpath(config_rootpath, subpath=None)

   Returns the latest version of a directory in the config_rootpath
       parent/kicad/
       - 7.0
       - 8.0

   latest_version_configpath('parent/kicad')  will return 'parent/kicad/8.0'


.. py:function:: get_default_paths()

   This function will not execute anything from pcbnew or KiCad.
   populate_optimal_paths() will do that


.. py:function:: populate_existing_default_paths()

.. py:function:: kipython_one_liner(script)

.. py:function:: get_ver()

.. py:function:: get_cfg_script()

.. py:function:: populate_optimal_paths()

   Populate the paths for kipython, pcbnew, and user settings directory.
   Runs pcbnew or kipython to ensure they are synchronized with one another.


.. py:function:: macwin_on_dlopen_error()

   If this is called, we have given up on importing pcbnew.py.
   Almost always this is because non-KiCad python is being used on Mac or Windows


.. py:function:: input_preferred_PATH()

   Prompts the user to select a preferred PATH for symbolic linking of 'kipython'.

   If no existing symlink is found, it lists valid destination paths for creating
   the 'kipython' symlink and prompts the user to select one. The user can cancel
   the operation by entering 'q' or press enter to select the default path.


.. py:function:: symlink_kipython_executable(dest_path=None)

   Creates a symbolic link to the kipython executable in a location that is in the PATH


.. py:data:: startup_script
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """### Auto generated by kigadgets initialization for pcbnew console
      import sys, pcbnew
      sys.path.append("{}")
      import kigadgets
      print('kigadgets (v{{}}) located at:'.format(kigadgets.__version__), kigadgets.__path__)
      from kigadgets.board import Board
      pcb = Board.from_editor()
      """

   .. raw:: html

      </details>



.. py:data:: plugin_script
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """### Auto generated by kigadgets initialization for pcbnew action plugins
      import sys
      sys.path.append("{}")
      """

   .. raw:: html

      </details>



.. py:function:: write_PyShell_startup_script(kicad_config_path, dry_run=False, cleanup=False)

.. py:function:: write_plugin_importer_script(kicad_config_path, dry_run=False, cleanup=False)

   Mac: this has no effect because you have to install kigadgets using kipython


.. py:function:: create_link(pcbnew_module_path=None, kicad_config_path=None, dry_run=False, cleanup=False)

   Create the link between kigadgets and pcbnew
   All of this works with pcbnew=None (i.e. not discoverable yet)


.. py:data:: help_msg
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      Create bidirectional link between kigadgets and pcbnew.
      
      Usage:
          python -m kigadgets [pcbnew_module_path] [kicad_config_path] [-n]
      
      Arguments:
          pcbnew_module_path   Path to the pcbnew.py module
          kicad_config_path   Path to the KiCad user configuration directory you want to use
          -n, --dry-run       Do not write any files, just show what would be done
      
      Path arguments are usually detected automatically.
      To use explicit arguments or custom install locations, see
      kigadgets.readthedocs.io/en/latest/installation.html#optional-installation-steps
      """

   .. raw:: html

      </details>



.. py:data:: parser

.. py:function:: cl_main()

.. py:function:: cl_geohash()

   Print geohash for a board - WIP