Coverage for pyngrok/conf.py: 90.70%

43 statements  

« prev     ^ index     » next       coverage.py v7.3.2, created at 2023-12-01 20:56 +0000

1import os 

2import platform 

3from typing import Optional, Callable 

4 

5from pyngrok.installer import get_ngrok_bin 

6from pyngrok.log import NgrokLog 

7 

8__author__ = "Alex Laird" 

9__copyright__ = "Copyright 2023, Alex Laird" 

10__version__ = "7.0.2" 

11 

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

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

14DEFAULT_CONFIG_PATH: Optional[str] = None 

15 

16system = platform.system().lower() 

17if system == "darwin": 

18 _config_rel_path = os.path.join("Library", "Application Support", "ngrok") 

19elif system in ["windows", "cygwin"]: 

20 _config_rel_path = os.path.join("AppData", "Local", "ngrok") 

21else: 

22 _config_rel_path = os.path.join(".config", "ngrok") 

23DEFAULT_NGROK_CONFIG_PATH = os.path.join(os.path.expanduser("~"), _config_rel_path, "ngrok.yml") 

24 

25 

26class PyngrokConfig: 

27 """ 

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

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

30 

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

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

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

34 

35 .. code-block:: python 

36 

37 from pyngrok import conf, ngrok 

38 

39 # Here we update the entire default config 

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

41 conf.set_default(pyngrok_config) 

42 

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

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

45 

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

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

48 ngrok.connect(pyngrok_config=pyngrok_config) 

49 """ 

50 

51 def __init__(self, 

52 ngrok_path: Optional[str] = None, 

53 config_path: Optional[str] = None, 

54 auth_token: Optional[str] = None, 

55 region: Optional[str] = None, 

56 monitor_thread: bool = True, 

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

58 startup_timeout: int = 15, 

59 max_logs: int = 100, 

60 request_timeout: float = 4, 

61 start_new_session: bool = False, 

62 ngrok_version: str = "v3", 

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

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

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

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

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

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

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

70 self.auth_token: Optional[str] = auth_token 

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

72 self.region: Optional[str] = region 

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

74 self.monitor_thread: bool = monitor_thread 

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

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

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

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

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

80 self.startup_timeout: int = startup_timeout 

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

82 self.max_logs: int = max_logs 

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

84 self.request_timeout: float = request_timeout 

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

86 self.start_new_session: bool = start_new_session 

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

88 self.ngrok_version: str = ngrok_version 

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

90 self.api_key: Optional[str] = api_key 

91 

92 

93_default_pyngrok_config: PyngrokConfig = PyngrokConfig() 

94 

95 

96def get_default() -> PyngrokConfig: 

97 """ 

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

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

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

101 

102 :return: The default ``pyngrok_config``. 

103 """ 

104 if _default_pyngrok_config is None: 

105 set_default(PyngrokConfig()) 

106 

107 return _default_pyngrok_config 

108 

109 

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

111 """ 

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

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

114 

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

116 """ 

117 global _default_pyngrok_config 

118 

119 _default_pyngrok_config = pyngrok_config 

120 

121 

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

123 """ 

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

125 

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

127 :return: The path to the config file. 

128 """ 

129 if pyngrok_config.config_path is not None: 

130 return pyngrok_config.config_path 

131 else: 

132 return DEFAULT_NGROK_CONFIG_PATH