Coverage for pyngrok/conf.py: 94.44%

1 import os

2 from typing import Optional, Callable

3

4 from pyngrok.installer import get_ngrok_bin

5 from pyngrok.log import NgrokLog

6

7 __author__ = "Alex Laird"

8 __copyright__ = "Copyright 2023, Alex Laird"

9 __version__ = "7.0.0"

10

11 BIN_DIR = os.path.normpath(os.path.join(os.path.abspath(os.path.dirname(__file__)), "bin"))

12 DEFAULT_NGROK_PATH = os.path.join(BIN_DIR, get_ngrok_bin())

13 DEFAULT_CONFIG_PATH: Optional[str] = None

14

15 DEFAULT_NGROK_CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".ngrok2", "ngrok.yml")

16

17

18 class PyngrokConfig:

19 """

20 An object containing ``pyngrok``'s configuration for interacting with the ``ngrok`` binary. All values are

21 optional when it is instantiated, and default values will be used for parameters not passed.

22

23 Use :func:`~pyngrok.conf.get_default` and :func:`~pyngrok.conf.set_default` to interact with the default

24 ``pyngrok_config``, or pass another instance of this object as the ``pyngrok_config`` keyword arg to most

25 methods in the :mod:`~pyngrok.ngrok` module to override the default.

26

27 .. code-block:: python

28

29 from pyngrok import conf, ngrok

30

31 # Here we update the entire default config

32 pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok")

33 conf.set_default(pyngrok_config)

34

35 # Here we update just one variable in the default config

36 conf.get_default().ngrok_path = "/usr/local/bin/ngrok"

37

38 # Here we leave the default config as-is and pass an override

39 pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok")

40 ngrok.connect(pyngrok_config=pyngrok_config)

41 """

42

43 def __init__(self,

44 ngrok_path: Optional[str] = None,

45 config_path: Optional[str] = None,

46 auth_token: Optional[str] = None,

47 region: Optional[str] = None,

48 monitor_thread: bool = True,

49 log_event_callback: Optional[Callable[[NgrokLog], None]] = None,

50 startup_timeout: int = 15,

51 max_logs: int = 100,

52 request_timeout: float = 4,

53 start_new_session: bool = False,

54 ngrok_version: str = "v3",

55 api_key: Optional[str] = None) -> None:

56 #: The path to the ``ngrok`` binary, defaults to the value in `conf.DEFAULT_NGROK_PATH

57 #: <index.html#config-file>`_.

58 self.ngrok_path: str = DEFAULT_NGROK_PATH if ngrok_path is None else ngrok_path

59 #: The path to the ``ngrok`` config, defaults to ``None`` and ``ngrok`` manages it.

60 self.config_path: Optional[str] = DEFAULT_CONFIG_PATH if config_path is None else config_path

61 #: A ``ngrok`` authtoken to pass to commands (overrides what is in the config).

62 self.auth_token: Optional[str] = auth_token

63 #: The region in which ``ngrok`` should start.

64 self.region: Optional[str] = region

65 #: Whether ``ngrok`` should continue to be monitored (for logs, etc.) after startup is complete.

66 self.monitor_thread: bool = monitor_thread

67 #: A callback that will be invoked each time ``ngrok`` emits a log. The function should take

68 #: one argument of type :py:class:`str`. ``monitor_thread`` must be set to ``True`` or the function will

69 # stop being called after ``ngrok`` finishes starting.

70 self.log_event_callback: Optional[Callable[[NgrokLog], None]] = log_event_callback

71 #: The max number of seconds to wait for ``ngrok`` to start before timing out.

72 self.startup_timeout: int = startup_timeout

73 #: The max number of logs to store in :class:`~pyngrok.process.NgrokProcess`'s ``logs`` variable.

74 self.max_logs: int = max_logs

75 #: The max timeout when making requests to ``ngrok``'s API.

76 self.request_timeout: float = request_timeout

77 #: Passed to :py:class:`subprocess.Popen` when launching ``ngrok``. (Python 3 and POSIX only).

78 self.start_new_session: bool = start_new_session

79 #: The major version of ``ngrok`` installed.

80 self.ngrok_version: str = ngrok_version

81 #: A ``ngrok`` API key.

82 self.api_key: Optional[str] = api_key

83

84

85 _default_pyngrok_config: PyngrokConfig = PyngrokConfig()

86

87

88 def get_default() -> PyngrokConfig:

89 """

90 Get the default config to be used with methods in the :mod:`~pyngrok.ngrok` module. To override the

91 default individually, the ``pyngrok_config`` keyword arg can also be passed to most of these methods,

92 or set a new default config with :func:`~pyngrok.conf.set_default`.

93

94 :return: The default ``pyngrok_config``.

95 """

96 if _default_pyngrok_config is None:

97 set_default(PyngrokConfig())

98

99 return _default_pyngrok_config

100

101

102 def set_default(pyngrok_config: PyngrokConfig) -> None:

103 """

104 Set a new default config to be used with methods in the :mod:`~pyngrok.ngrok` module. To override the

105 default individually, the ``pyngrok_config`` keyword arg can also be passed to most of these methods.

106

107 :param pyngrok_config: The new ``pyngrok_config`` to be used by default.

108 """

109 global _default_pyngrok_config

110

111 _default_pyngrok_config = pyngrok_config

112

113

114 def get_config_path(pyngrok_config: PyngrokConfig) -> str:

115 """

116 Return the ``config_path`` if set on the given ``pyngrok_configg``, otherwise return ``ngrok``'s default path.

117

118 :param pyngrok_config: The ``pyngrok`` configuration to first check for a ``config_path``.

119 :return: The path to the config file.

120 """

121 if pyngrok_config.config_path is not None:

122 return pyngrok_config.config_path

123 else:

124 return DEFAULT_NGROK_CONFIG_PATH