Coverage for sources/appcore/state.py: 100%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Immutable global state. ''' 

22 

23 

24from . import __ 

25from . import application as _application 

26from . import distribution as _distribution 

27 

28 

29class DirectorySpecies( __.enum.Enum ): # TODO: Python 3.11: StrEnum 

30 ''' Possible species for locations. ''' 

31 

32 Cache = 'cache' 

33 Data = 'data' 

34 State = 'state' 

35 

36 

37class Globals( __.immut.DataclassObject ): 

38 ''' Immutable global data. Required by some library functions. ''' 

39 

40 application: _application.Information 

41 configuration: __.accret.Dictionary[ str, __.typx.Any ] 

42 directories: __.pdirs.PlatformDirs 

43 distribution: _distribution.Information 

44 exits: __.ctxl.AsyncExitStack 

45 

46 def as_dictionary( self ) -> __.cabc.Mapping[ str, __.typx.Any ]: 

47 ''' Returns shallow copy of state. ''' 

48 return { 

49 field.name: getattr( self, field.name ) 

50 for field in __.dcls.fields( self ) } 

51 

52 def provide_cache_location( self, *appendages: str ) -> __.Path: 

53 ''' Provides cache location from configuration. ''' 

54 return self.provide_location( DirectorySpecies.Cache, *appendages ) 

55 

56 def provide_data_location( self, *appendages: str ) -> __.Path: 

57 ''' Provides data location from configuration. ''' 

58 return self.provide_location( DirectorySpecies.Data, *appendages ) 

59 

60 def provide_state_location( self, *appendages: str ) -> __.Path: 

61 ''' Provides state location from configuration. ''' 

62 return self.provide_location( DirectorySpecies.State, *appendages ) 

63 

64 def provide_location( 

65 self, species: DirectorySpecies, *appendages: str 

66 ) -> __.Path: 

67 ''' Provides particular species of location from configuration. ''' 

68 species_name = species.value 

69 base = getattr( self.directories, f"user_{species_name}_path" ) 

70 spec = self.configuration.get( 'locations', { } ).get( species_name ) 

71 if spec: 

72 args: dict[ str, str | __.Path ] = { 

73 f"user_{species_name}": base, 

74 'user_home': __.Path.home( ), 

75 'application_name': self.application.name, 

76 } 

77 base = __.Path( spec.format( **args ) ) 

78 if appendages: return base.joinpath( *appendages ) 

79 return base