Coverage for pyngrok/conf.py: 94.44%

36 statements  

« prev     ^ index     » next       coverage.py v7.3.1, created at 2023-09-20 14:14 +0000

1import os 

2from typing import Optional, Callable 

3 

4from pyngrok.installer import get_ngrok_bin 

5from pyngrok.log import NgrokLog 

6 

7__author__ = "Alex Laird" 

8__copyright__ = "Copyright 2023, Alex Laird" 

9__version__ = "7.0.0" 

10 

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

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

13DEFAULT_CONFIG_PATH: Optional[str] = None 

14 

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

16 

17 

18class 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 

88def 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 

102def 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 

114def 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