Coverage for pyngrok/conf.py: 96.55%

1 import os

2

3 from pyngrok.installer import get_ngrok_bin

4

5 __author__ = "Alex Laird"

6 __copyright__ = "Copyright 2023, Alex Laird"

7 __version__ = "6.0.0"

8

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

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

11 DEFAULT_CONFIG_PATH = None

12

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

14

15 _default_pyngrok_config = None

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 :var ngrok_path: The path to the ``ngrok`` binary, defaults to the value in

43 `conf.DEFAULT_NGROK_PATH <index.html#config-file>`_

44 :vartype ngrok_path: str

45 :var config_path: The path to the ``ngrok`` config, defaults to ``None`` and ``ngrok`` manages it.

46 :vartype config_path: str

47 :var auth_token: An authtoken to pass to commands (overrides what is in the config).

48 :vartype auth_token: str

49 :var region: The region in which ``ngrok`` should start.

50 :vartype region: str

51 :var monitor_thread: Whether ``ngrok`` should continue to be monitored (for logs, etc.) after startup

52 is complete.

53 :vartype monitor_thread: bool

54 :var log_event_callback: A callback that will be invoked each time ``ngrok`` emits a log. ``monitor_thread``

55 must be set to ``True`` or the function will stop being called after ``ngrok`` finishes starting.

56 :vartype log_event_callback: types.FunctionType

57 :var startup_timeout: The max number of seconds to wait for ``ngrok`` to start before timing out.

58 :vartype startup_timeout: int

59 :var max_logs: The max number of logs to store in :class:`~pyngrok.process.NgrokProcess`'s ``logs`` variable.

60 :vartype max_logs: int

61 :var request_timeout: The max timeout when making requests to ``ngrok``'s API.

62 :vartype request_timeout: float

63 :var start_new_session: Passed to :py:class:`subprocess.Popen` when launching ``ngrok``. (Python 3 and POSIX only)

64 :vartype start_new_session: bool

65 :var ngrok_version: The major version of ``ngrok`` installed.

66 :vartype ngrok_version: str

67 """

68

69 def __init__(self,

70 ngrok_path=None,

71 config_path=None,

72 auth_token=None,

73 region=None,

74 monitor_thread=True,

75 log_event_callback=None,

76 startup_timeout=15,

77 max_logs=100,

78 request_timeout=4,

79 start_new_session=False,

80 ngrok_version="v3"):

81 self.ngrok_path = DEFAULT_NGROK_PATH if ngrok_path is None else ngrok_path

82 self.config_path = DEFAULT_CONFIG_PATH if config_path is None else config_path

83 self.auth_token = auth_token

84 self.region = region

85 self.monitor_thread = monitor_thread

86 self.log_event_callback = log_event_callback

87 self.startup_timeout = startup_timeout

88 self.max_logs = max_logs

89 self.request_timeout = request_timeout

90 self.start_new_session = start_new_session

91 self.ngrok_version = ngrok_version

92

93

94 def get_default():

95 """

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

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

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

99

100 :return: The default ``pyngrok_config``.

101 :rtype: PyngrokConfig

102 """

103 if _default_pyngrok_config is None:

104 set_default(PyngrokConfig())

105

106 return _default_pyngrok_config

107

108

109 def set_default(pyngrok_config):

110 """

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

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

113

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

115 :type pyngrok_config: PyngrokConfig

116 """

117 global _default_pyngrok_config

118

119 _default_pyngrok_config = pyngrok_config