ScriptCollection 4.4.41__py3-none-any.whl → 4.4.43__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -40,7 +40,7 @@ from .ProgramRunnerBase import ProgramRunnerBase
40
40
  from .ProgramRunnerPopen import ProgramRunnerPopen
41
41
  from .SCLog import SCLog, LogLevel
42
42
 
43
- version = "4.4.41"
43
+ version = "4.4.43"
44
44
  __version__ = version
45
45
 
46
46
  class VSCodeWorkspaceShellTask:
@@ -198,7 +198,7 @@ class ScriptCollectionCore:
198
198
 
199
199
  # The purpose of this property is to use it when testing your code which uses scriptcollection for external program-calls.
200
200
  # Do not change this value for productive environments.
201
- mock_program_calls: bool = False#TODO remove this variable. When someone want to mock program-calls then the ProgramRunnerMock can be used instead
201
+ mock_program_calls: bool = False#TODO remove this variable. When someone wants to mock program-calls then the ProgramRunnerMock can be used instead
202
202
  # The purpose of this property is to use it when testing your code which uses scriptcollection for external program-calls.
203
203
  execute_program_really_if_no_mock_call_is_defined: bool = False
204
204
  __mocked_program_calls: list = None
@@ -551,7 +551,7 @@ class ScriptCollectionCore:
551
551
  @GeneralUtilities.check_arguments
552
552
  def split_image_address_and_tag(image_with_tag: str) -> tuple[str, str]:
553
553
  """Splits an image-address which contains a tag into the address and the tag.
554
- Example: "myregistry.example.com:5000/debian:12" is splitted into ("myregistry.example.com:5000/debian", "12").
554
+ Example: "myregistry.example.com:5000/debian:12" is split into ("myregistry.example.com:5000/debian", "12").
555
555
  If the given address does not contain a tag then "latest" is returned as tag, which is the tag docker assumes in this case too."""
556
556
  last_colon_index = image_with_tag.rfind(":")
557
557
  last_slash_index = image_with_tag.rfind("/")
@@ -788,10 +788,10 @@ class ScriptCollectionCore:
788
788
  if (result[0] != 0):
789
789
  return False
790
790
  if (not GeneralUtilities.contains_line(result[1].splitlines(), f"gpg\\:\\ using\\ [A-Za-z0-9]+\\ key\\ [A-Za-z0-9]+{key}")):
791
- # TODO check whether this works on machines where gpg is installed in another langauge than english
791
+ # TODO check whether this works on machines where gpg is installed in another language than english
792
792
  return False
793
793
  if (not GeneralUtilities.contains_line(result[1].splitlines(), "gpg\\:\\ Good\\ signature\\ from")):
794
- # TODO check whether this works on machines where gpg is installed in another langauge than english
794
+ # TODO check whether this works on machines where gpg is installed in another language than english
795
795
  return False
796
796
  return True
797
797
 
@@ -825,7 +825,7 @@ class ScriptCollectionCore:
825
825
  elif exit_code == 1:
826
826
  return False
827
827
  else:
828
- raise ValueError(f'Can not calculate if {ancestor} is an ancestor of {descendant} in repository {repository_folder}. Outout of "{repository_folder}> git merge-base --is-ancestor {ancestor} {descendant}": Exitcode: {exit_code}; StdOut: {result[1]}; StdErr: {result[2]}.')
828
+ raise ValueError(f'Can not calculate if {ancestor} is an ancestor of {descendant} in repository {repository_folder}. Output of "{repository_folder}> git merge-base --is-ancestor {ancestor} {descendant}": Exitcode: {exit_code}; StdOut: {result[1]}; StdErr: {result[2]}.')
829
829
 
830
830
  @GeneralUtilities.check_arguments
831
831
  def __git_changes_helper(self, repository_folder: str, arguments_as_array: list[str]) -> bool:
@@ -943,6 +943,11 @@ class ScriptCollectionCore:
943
943
 
944
944
  @GeneralUtilities.check_arguments
945
945
  def git_push(self, folder: str, remotename: str, localbranchname: str, remotebranchname: str, forcepush: bool = False, pushalltags: bool = True, verbosity: LogLevel = LogLevel.Quiet,resurse_submodules:bool=False) -> None:
946
+ """Pushes localbranchname to remotebranchname on the given remote (with pushalltags also all tags).
947
+ Without forcepush (and if folder is not a bare repository) the push is skipped (only logged on debug-level) when the
948
+ remote-branch is not strictly behind the local-branch, i.e. when it is equal, ahead or diverged (see git_branch_is_pushable),
949
+ because a push would then fail with a non-fast-forward-error or would have nothing to do. In that case the tags are not pushed
950
+ either. Note that this check fetches from the remote. Raises a ValueError if the push itself fails."""
946
951
  self.is_git_or_bare_git_repository(folder)
947
952
  if not forcepush and not self.is_bare_git_repository(folder):
948
953
  # If the remote-branch already contains the current commit or is ahead of the local-branch there is nothing to push and a
@@ -1170,7 +1175,7 @@ class ScriptCollectionCore:
1170
1175
  self.git_merge(repository_folder, f"{remote}/{branch}", branch)
1171
1176
  self.git_push_with_retry(repository_folder, remote, branch, branch)
1172
1177
  self.git_checkout(repository_folder, branch)
1173
- #TODO opeional: checkfor merge conflicts and if there is one merge conflict print a warning
1178
+ #TODO optional: check for merge conflicts and if there is one merge conflict print a warning
1174
1179
 
1175
1180
  @GeneralUtilities.check_arguments
1176
1181
  def git_merge_abort(self, directory: str) -> None:
@@ -1442,7 +1447,7 @@ class ScriptCollectionCore:
1442
1447
  self.assert_is_git_repository(repository_folder)
1443
1448
  git_folder = repository_folder + "/.git"
1444
1449
  if not self.is_folder(git_folder):
1445
- raise ValueError(f"Converting '{repository_folder}' to a bare repository not possible. The folder '{git_folder}' does not exist. Converting is currently only supported when the git-folder is a direct folder in a repository and not a reference to another location.")
1450
+ raise ValueError(f"Converting '{repository_folder}' to a bare repository is not possible. The folder '{git_folder}' does not exist. Converting is currently only supported when the git-folder is a direct folder in a repository and not a reference to another location.")
1446
1451
  target_folder: str = repository_folder + ".git"
1447
1452
  GeneralUtilities.ensure_directory_exists(target_folder)
1448
1453
  GeneralUtilities.move_content_of_folder(git_folder, target_folder)
@@ -1489,7 +1494,7 @@ class ScriptCollectionCore:
1489
1494
  normalized_line = line.replace("\r", "")
1490
1495
  result.append(normalized_line)
1491
1496
  else:
1492
- raise ValueError(f"Fatal error occurrs while checking whether file '{path}' exists. StdErr: '{stderr}'")
1497
+ raise ValueError(f"Fatal error occurred while checking whether file '{path}' exists. StdErr: '{stderr}'")
1493
1498
  result = [item for item in result if GeneralUtilities.string_has_nonwhitespace_content(item)]
1494
1499
  return result
1495
1500
 
@@ -1503,10 +1508,10 @@ class ScriptCollectionCore:
1503
1508
  if exit_code == 0:
1504
1509
  return True
1505
1510
  elif exit_code == 1:
1506
- raise ValueError(f"Not calculatable whether file '{path}' exists. StdErr: '{stderr}'")
1511
+ raise ValueError(f"Not calculable whether file '{path}' exists. StdErr: '{stderr}'")
1507
1512
  elif exit_code == 2:
1508
1513
  return False
1509
- raise ValueError(f"Fatal error occurrs while checking whether file '{path}' exists. StdErr: '{stderr}'")
1514
+ raise ValueError(f"Fatal error occurred while checking whether file '{path}' exists. StdErr: '{stderr}'")
1510
1515
 
1511
1516
  @GeneralUtilities.check_arguments
1512
1517
  def get_size(self, path: str) -> int:
@@ -1518,7 +1523,7 @@ class ScriptCollectionCore:
1518
1523
  if exit_code == 0:
1519
1524
  return int(stdout.replace("\r","").replace("\n","").strip())
1520
1525
  else:
1521
- raise ValueError(f"Fatal error occurrs while checking whether file '{path}' exists. StdErr: '{stderr}'")
1526
+ raise ValueError(f"Fatal error occurred while checking whether file '{path}' exists. StdErr: '{stderr}'")
1522
1527
 
1523
1528
  @GeneralUtilities.check_arguments
1524
1529
  def is_folder(self, path: str) -> bool:
@@ -1530,10 +1535,10 @@ class ScriptCollectionCore:
1530
1535
  if exit_code == 0:
1531
1536
  return True
1532
1537
  elif exit_code == 1:
1533
- raise ValueError(f"Not calculatable whether folder '{path}' exists. StdErr: '{stderr}'")
1538
+ raise ValueError(f"Not calculable whether folder '{path}' exists. StdErr: '{stderr}'")
1534
1539
  elif exit_code == 2:
1535
1540
  return False
1536
- raise ValueError(f"Fatal error occurrs while checking whether folder '{path}' exists. StdErr: '{stderr}'")
1541
+ raise ValueError(f"Fatal error occurred while checking whether folder '{path}' exists. StdErr: '{stderr}'")
1537
1542
 
1538
1543
 
1539
1544
 
@@ -1546,7 +1551,7 @@ class ScriptCollectionCore:
1546
1551
  content_bytes = content.encode('utf-8')
1547
1552
  base64_bytes = base64.b64encode(content_bytes)
1548
1553
  base64_string = base64_bytes.decode('utf-8')
1549
- self.run_program_argsasarray("scsetfilecontent", ["--path", path, "--argumentisinbase64", "--content", base64_string]) # works platform-indepent
1554
+ self.run_program_argsasarray("scsetcontentoffile", ["--path", path, "--argumentisinbase64", "--content", base64_string]) # works platform-independent
1550
1555
 
1551
1556
  @GeneralUtilities.check_arguments
1552
1557
  def file_contains_content(self, path: str, content: str, treat_content_as_regex: bool = False, case_sensitive: bool = True, encoding: str = "utf-8") -> bool:
@@ -1573,11 +1578,11 @@ class ScriptCollectionCore:
1573
1578
  if self.is_file(path):
1574
1579
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("scremovefile", ["--path", path], throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1575
1580
  if exit_code != 0:
1576
- raise ValueError(f"Fatal error occurrs while removing file '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1581
+ raise ValueError(f"Fatal error occurred while removing file '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1577
1582
  if self.is_folder(path):
1578
1583
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("scremovefolder", ["--path", path], throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1579
1584
  if exit_code != 0:
1580
- raise ValueError(f"Fatal error occurrs while removing folder '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1585
+ raise ValueError(f"Fatal error occurred while removing folder '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1581
1586
 
1582
1587
  @GeneralUtilities.check_arguments
1583
1588
  def rename(self, source: str, target: str) -> None:
@@ -1587,7 +1592,7 @@ class ScriptCollectionCore:
1587
1592
  else:
1588
1593
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("screname", ["--source", source, "--target", target], throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1589
1594
  if exit_code != 0:
1590
- raise ValueError(f"Fatal error occurrs while renaming '{source}' to '{target}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1595
+ raise ValueError(f"Fatal error occurred while renaming '{source}' to '{target}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1591
1596
 
1592
1597
  @GeneralUtilities.check_arguments
1593
1598
  def copy(self, source: str, target: str) -> None:
@@ -1605,7 +1610,7 @@ class ScriptCollectionCore:
1605
1610
  else:
1606
1611
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("sccopy", ["--source", source, "--target", target], throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1607
1612
  if exit_code != 0:
1608
- raise ValueError(f"Fatal error occurrs while copying '{source}' to '{target}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1613
+ raise ValueError(f"Fatal error occurred while copying '{source}' to '{target}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1609
1614
 
1610
1615
  @GeneralUtilities.check_arguments
1611
1616
  def get_file_content(self, file: str, encoding: str = "utf-8", from_line: int = None, to_line: int = None) -> str:
@@ -1667,7 +1672,7 @@ class ScriptCollectionCore:
1667
1672
 
1668
1673
  if not os.path.isdir(folder):
1669
1674
  if create_necessary_folder:
1670
- GeneralUtilities.ensure_directory_exists(folder) # TODO check if this also create nested folders if required
1675
+ GeneralUtilities.ensure_directory_exists(folder) # TODO check if this also creates nested folders if required
1671
1676
  else:
1672
1677
  raise ValueError(f"Folder '{folder}' does not exist.")
1673
1678
 
@@ -1683,7 +1688,7 @@ class ScriptCollectionCore:
1683
1688
 
1684
1689
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("sccreatefile", arguments, throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1685
1690
  if exit_code != 0:
1686
- raise ValueError(f"Fatal error occurrs while create file '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1691
+ raise ValueError(f"Fatal error occurred while creating file '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1687
1692
 
1688
1693
  @GeneralUtilities.check_arguments
1689
1694
  def create_folder(self, path: str, error_if_already_exists: bool, create_necessary_folder: bool) -> None:
@@ -1701,7 +1706,7 @@ class ScriptCollectionCore:
1701
1706
 
1702
1707
  if not os.path.isdir(folder):
1703
1708
  if create_necessary_folder:
1704
- GeneralUtilities.ensure_directory_exists(folder) # TODO check if this also create nested folders if required
1709
+ GeneralUtilities.ensure_directory_exists(folder) # TODO check if this also creates nested folders if required
1705
1710
  else:
1706
1711
  raise ValueError(f"Folder '{folder}' does not exist.")
1707
1712
 
@@ -1717,7 +1722,7 @@ class ScriptCollectionCore:
1717
1722
 
1718
1723
  exit_code, stdout, stderr, _ = self.run_program_argsasarray("sccreatefolder", arguments, throw_exception_if_exitcode_is_not_zero=False) # works platform-indepent
1719
1724
  if exit_code != 0:
1720
- raise ValueError(f"Fatal error occurrs while create folder '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1725
+ raise ValueError(f"Fatal error occurred while creating folder '{path}'; Exitcode: '{exit_code}'; StdOut: '{stdout}'. StdErr: '{stderr}'")
1721
1726
 
1722
1727
  @GeneralUtilities.check_arguments
1723
1728
  def __sort_fmd(self, line: str):
@@ -2400,7 +2405,7 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
2400
2405
 
2401
2406
  @GeneralUtilities.check_arguments
2402
2407
  def get_file_permission(self, file: str) -> str:
2403
- """This function returns an usual octet-triple, for example "700"."""
2408
+ """This function returns a usual octet-triple, for example "700"."""
2404
2409
  ls_output: str = self.run_ls_for_folder(file)
2405
2410
  return self.__get_file_permission_helper(ls_output)
2406
2411
 
@@ -2461,7 +2466,7 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
2461
2466
 
2462
2467
  @GeneralUtilities.check_arguments
2463
2468
  def set_permission(self, file_or_folder: str, permissions: str, recursive: bool = False) -> None:
2464
- """This function expects an usual octet-triple, for example "700"."""
2469
+ """This function expects a usual octet-triple, for example "700"."""
2465
2470
  args = []
2466
2471
  if recursive:
2467
2472
  args.append("--recursive")
@@ -2593,6 +2598,20 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
2593
2598
 
2594
2599
  @GeneralUtilities.check_arguments
2595
2600
  def run_program_argsasarray(self, program: str, arguments_as_array: list[str] = [], working_directory: str = None, print_errors_as_information: bool = False, log_file: str = None, timeoutInSeconds: int = None, addLogOverhead: bool = False, title: str = None, log_namespace: str = "", arguments_for_log: list[str] = None, throw_exception_if_exitcode_is_not_zero: bool = True, custom_argument: object = None, interactive: bool = False, print_live_output: bool = False, env_vars: dict = None) -> tuple[int, str, str, int]:
2601
+ """Runs a program synchronously and returns (exitcode, stdout, stderr, pid).
2602
+ Every element of arguments_as_array is passed to the program as exactly one argument; nothing is split at spaces.
2603
+ A relative working_directory is resolved against the current working-directory, None means the current working-directory
2604
+ (both only when the program is executed locally). A ValueError is raised if that folder does not exist.
2605
+ stdout and stderr are returned without empty lines and without the trailing linebreak of each line. If log_file is given,
2606
+ their lines are additionally appended to that file (first the stdout-lines, then the stderr-lines).
2607
+ arguments_for_log replaces the arguments in the log-output, which is meant to keep secrets which are passed as argument out of the log.
2608
+ Failure-behavior: if throw_exception_if_exitcode_is_not_zero is set (default) a ValueError (containing stdout and stderr) is
2609
+ raised when the exitcode is not 0. A TimeoutError is raised if the program does not finish within timeoutInSeconds; the process
2610
+ is killed then.
2611
+ If mocking is enabled and a mock-call is defined for this program-call, the mocked result is returned and the program is not
2612
+ executed; if no matching mock-call is defined a LookupError is raised unless execute_program_really_if_no_mock_call_is_defined is set.
2613
+ If call_program_runner_directly is set, the call is passed to the program-runner directly, without mocking, logging and
2614
+ exitcode-check."""
2596
2615
  if self.call_program_runner_directly:
2597
2616
  return self.program_runner.run_program_argsasarray(program, arguments_as_array, working_directory, custom_argument, interactive, env_vars)
2598
2617
  try:
@@ -2911,6 +2930,9 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
2911
2930
 
2912
2931
  @GeneralUtilities.check_arguments
2913
2932
  def increment_version(self, input_version: str, increment_major: bool, increment_minor: bool, increment_patch: bool) -> str:
2933
+ """Increments a version in the format "major.minor.patch". Incrementing a part resets the less significant parts to 0;
2934
+ if several flags are set they are applied in the order major, minor, patch (so for example major and patch together
2935
+ turn "1.2.3" into "2.0.1"). Raises a ValueError if input_version does not consist of exactly three parts."""
2914
2936
  splitted = input_version.split(".")
2915
2937
  GeneralUtilities.assert_condition(len(splitted) == 3, f"Version '{input_version}' does not have the 'major.minor.patch'-pattern.")
2916
2938
  major = int(splitted[0])
@@ -3043,6 +3065,10 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
3043
3065
 
3044
3066
  @GeneralUtilities.check_arguments
3045
3067
  def get_real_git_folder(self,repository_folder:str) -> str:
3068
+ """Returns the folder which contains the git-data of the repository. This is "<repository>/.git" for a normal repository;
3069
+ for a submodule or a worktree (where ".git" is a file containing "gitdir: <path>") it is the folder this file points to
3070
+ (a relative path is resolved against repository_folder).
3071
+ Raises a ValueError if there is no ".git", if the ".git"-file has an unexpected format or if the folder it points to does not exist."""
3046
3072
  git_folder = os.path.join(repository_folder, ".git")
3047
3073
  if os.path.isfile(git_folder):
3048
3074
  with open(git_folder, "r", encoding="utf-8") as f:
@@ -3066,22 +3092,6 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
3066
3092
  def is_patch_version(version_string: str) -> bool:
3067
3093
  return not version_string.endswith(".0")
3068
3094
 
3069
- @GeneralUtilities.check_arguments
3070
- def get_version_from_gitversion(self, folder: str, variable: str,use_cache:bool=True) -> str:
3071
- git_folder:str=self.get_real_git_folder(folder)
3072
- cache_folder:str=os.path.join(git_folder,"gitversion_cache")
3073
- gitversion_timeout_in_seconds: int = 900
3074
- if not use_cache:
3075
- GeneralUtilities.ensure_directory_does_not_exist(cache_folder)
3076
- gitversion_timeout_in_seconds=3600
3077
- # /nofetch and /nonormalize: avoid network calls / branch normalization (no auth, no DNS, deterministic in containers and offline).
3078
- # called twice as workaround for issue 1877 in gitversion ( https://github.com/GitTools/GitVersion/issues/1877 )
3079
- # timeoutInSeconds: gitversion finishes within seconds on a normal repository; enforce a timeout so a hanging gitversion-process (observed in some build-containers) aborts the build instead of waiting forever.
3080
- result = self.run_program_argsasarray("gitversion", ["/nofetch", "/nonormalize", "/showVariable", variable], folder, timeoutInSeconds=gitversion_timeout_in_seconds)
3081
- result = self.run_program_argsasarray("gitversion", ["/nofetch", "/nonormalize", "/showVariable", variable], folder, timeoutInSeconds=gitversion_timeout_in_seconds)
3082
- result = GeneralUtilities.strip_new_line_character(result[1])
3083
- return result
3084
-
3085
3095
  @GeneralUtilities.check_arguments
3086
3096
  def generate_certificate_authority(self, folder: str, name: str, subj_c: str, subj_st: str, subj_l: str, subj_o: str, subj_ou: str, days_until_expire: int = None, password: str = None) -> None:
3087
3097
  if days_until_expire is None:
@@ -3093,6 +3103,12 @@ resolving a name requires fontconfig, which does not exist on every system ffmpe
3093
3103
 
3094
3104
  @GeneralUtilities.check_arguments
3095
3105
  def generate_certificate(self, folder: str, domain: str, filename: str, subj_c: str, subj_st: str, subj_l: str, subj_o: str, subj_ou: str, days_until_expire: int = None, password: str = None) -> None:
3106
+ """Generates a self-signed certificate for the given domain using openssl (which must be available as command).
3107
+ The following files are written into folder (existing files are overwritten): "<filename>.key" (unencrypted private key),
3108
+ "<filename>.unsigned.crt", "<filename>.selfsigned.pfx" (protected by the password), "<filename>.password" (the password in
3109
+ plain text) and "<filename>.san.conf" (configuration which can be used to create a sign-request for the same subject).
3110
+ If password is None a random password is generated. days_until_expire defaults to 397 days.
3111
+ Raises a ValueError if an openssl-call fails."""
3096
3112
  if days_until_expire is None:
3097
3113
  days_until_expire = 397
3098
3114
  if password is None:
@@ -3413,14 +3429,14 @@ TXDX
3413
3429
 
3414
3430
  TXDX
3415
3431
 
3416
- ## Deployment-proecsses
3432
+ ## Deployment-processes
3417
3433
 
3418
3434
  TXDX""")
3419
3435
  self.__add_chapter(main_reference_file, reference_content_folder, 8, 'Crosscutting Concepts', """TXDX""")
3420
3436
  self.__add_chapter(main_reference_file, reference_content_folder, 9, 'Architectural Decisions', """## Decision-board
3421
3437
 
3422
3438
  | Decision-identifier | Date | Decision | Reason and notes |
3423
- | ------------------- | ---- | -------- | ---------------- |""") # empty because there are no decsions yet
3439
+ | ------------------- | ---- | -------- | ---------------- |""") # empty because there are no decisions yet
3424
3440
  self.__add_chapter(main_reference_file, reference_content_folder, 10, 'Quality Requirements', """TXDX""")
3425
3441
  self.__add_chapter(main_reference_file, reference_content_folder, 11, 'Risks and Technical Debt', """## Risks
3426
3442
 
@@ -3428,7 +3444,7 @@ Currently there are no known risks.
3428
3444
 
3429
3445
  ## Technical debts
3430
3446
 
3431
- Currently there are no technical depts.""")
3447
+ Currently there are no technical debts.""")
3432
3448
  self.__add_chapter(main_reference_file, reference_content_folder, 12, 'Glossary', """## Terms
3433
3449
 
3434
3450
  | Term | Meaning |
@@ -3444,7 +3460,7 @@ Currently there are no technical depts.""")
3444
3460
 
3445
3461
  | Responsibility | Name and contact-information |
3446
3462
  | --------------- | ---------------------------- |
3447
- | Pdocut-owner | TXDX |
3463
+ | Product-owner | TXDX |
3448
3464
  | Product-manager | TXDX |
3449
3465
  | Support | TXDX |
3450
3466
 
@@ -3951,6 +3967,15 @@ OCR-content:
3951
3967
 
3952
3968
  @GeneralUtilities.check_arguments
3953
3969
  def start_local_test_service(self, file: str):
3970
+ """Starts the test-service defined by the "docker-compose.yml" located in the same folder as file (typically the
3971
+ start-script of the test-service) in the background, using the compose-project-name "test<foldername>" (lowercase) and the
3972
+ "Parameters.env" next to it if it exists. Containers whose names are equal to the names of the services of the compose-file
3973
+ are removed forcibly first.
3974
+ Outside of a build-container the exposed ports of the services are published to localhost (using a temporary override-file),
3975
+ so the tests running on the host can reach them. Inside a build-container no port is published (to avoid port-conflicts between
3976
+ concurrent pipelines on the same host); instead the build-container is attached to the networks of the compose-file and the
3977
+ container-names are registered in its /etc/hosts, so the tests can use the container-names as hostnames.
3978
+ Raises a ValueError if starting the services fails."""
3954
3979
  example_folder = os.path.dirname(file)
3955
3980
  docker_compose_file = os.path.join(example_folder, "docker-compose.yml")
3956
3981
  for service in self.get_services_from_yaml_file(docker_compose_file):
@@ -455,7 +455,7 @@ class TFCPS_CodeUnitSpecific_DotNet_Functions(TFCPS_CodeUnitSpecific_Base):
455
455
  for (level, message, file, line) in diagnostics:
456
456
  location = f" ({file}:{line})" if file else ""
457
457
  self._protected_sc.log.log(f"{message}{location}", level)
458
- if level == LogLevel.Error:#should not occurr on scbuildcodeunits because then the build would have failed already but you can also run this script manually.
458
+ if level == LogLevel.Error:#should not occur on scbuildcodeunits because then the build would have failed already but you can also run this script manually.
459
459
  has_errors = True
460
460
  if has_errors:
461
461
  raise ValueError("Linting-issues occurred.")
@@ -479,8 +479,9 @@ class TFCPS_CodeUnitSpecific_Flutter_Functions(TFCPS_CodeUnitSpecific_Base):
479
479
  def translate_safe(self, base_language: str = "en", throw_if_no_credentials: bool = False) -> None:
480
480
  """Translates every not-yet-translated segment of Other/Resources/Translations/messages.<language>.xlf via
481
481
  LibreTranslate, if a translation-service is configured. The translation-service can be configured by creating
482
- a file at ~/.ScriptCollection/TranslationServiceProperties.txt with the content
483
- "LibreTranslateAPI=your_api_server_url" (matching TFCPS_CodeUnitSpecific_NodeJS_Functions.translate_safe)."""
482
+ a file at ~/.ScriptCollection/GlobalCache/TranslationServiceProperties.txt with the content
483
+ "LibreTranslateAPI=your_api_server_url" (matching TFCPS_CodeUnitSpecific_NodeJS_Functions.translate_safe).
484
+ If no translation-service is configured nothing is translated, or a ValueError is raised if throw_if_no_credentials is set."""
484
485
  translationservice_file = os.path.join(self._protected_sc.get_global_cache_folder(), "TranslationServiceProperties.txt")
485
486
  api_server: str | None = None
486
487
  if os.path.isfile(translationservice_file):
@@ -74,7 +74,7 @@ class TFCPS_CodeUnitSpecific_NodeJS_Functions(TFCPS_CodeUnitSpecific_Base):
74
74
  os.rename(os.path.join(coverage_folder, "cobertura-coverage.xml"), target_file)
75
75
  self.__rename_packagename_in_coverage_file(target_file, codeunit_name)
76
76
 
77
- # adapt backslashs to slashs
77
+ # adapt backslashes to slashes
78
78
  content = GeneralUtilities.read_text_from_file(target_file)
79
79
  content = re.sub('\\\\', '/', content)
80
80
  GeneralUtilities.write_text_to_file(target_file, content)
@@ -244,7 +244,7 @@ class TFCPS_CodeUnitSpecific_NodeJS_Functions(TFCPS_CodeUnitSpecific_Base):
244
244
 
245
245
  @GeneralUtilities.check_arguments
246
246
  def translate_safe(self,base_language:str="en", throw_if_no_credentials:bool=False)->None:
247
- """Translates XLF files if a translation service is configured. The translation service can be configured by creating a file at ~/.ScriptCollection/TranslationServiceProperties.txt with the content 'LibreTranslateAPI=your_api_server_url'."""
247
+ """Translates XLF files if a translation service is configured. The translation service can be configured by creating a file at ~/.ScriptCollection/GlobalCache/TranslationServiceProperties.txt with the content 'LibreTranslateAPI=your_api_server_url'. If no translation service is configured nothing is translated, or a ValueError is raised if throw_if_no_credentials is set."""
248
248
  translationservice_file:str=self._protected_sc.get_global_cache_folder()+"/TranslationServiceProperties.txt"
249
249
  api_server:str=None
250
250
  if os.path.isfile(translationservice_file):
@@ -29,7 +29,7 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
29
29
  tfcps_Tools_General:TFCPS_Tools_General = None
30
30
  _protected_sc:ScriptCollectionCore = None
31
31
  __is_pre_merge:bool=False
32
- __validate_developers_of_repository:bool=True#TODO must be setable to false
32
+ __validate_developers_of_repository:bool=True#TODO must be settable to false
33
33
  codeunit_namespace:str="https://projects.aniondev.de/PublicProjects/Common/ProjectTemplates/-/tree/main/Conventions/RepositoryStructure/CommonProjectStructure"
34
34
 
35
35
  def __init__(self,current_file:str,verbosity:LogLevel,target_envionment_type:str,use_cache:bool,is_pre_merge:bool):
@@ -217,7 +217,7 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
217
217
  for actual_author in actual_authors:
218
218
  if not (actual_author) in expected_authors:
219
219
  actual_author_formatted = f"{actual_author[0]} <{actual_author[1]}>"
220
- raise ValueError(f'Author/Comitter "{actual_author_formatted}" is not in the codeunit-developer-team. If {actual_author} is a authorized developer for this codeunit you should consider defining this in the codeunit-file or adapting the name using a .mailmap-file (see https://git-scm.com/docs/gitmailmap). The developer-team-check can also be disabled using the property validate_developers_of_repository.')
220
+ raise ValueError(f'Author/Committer "{actual_author_formatted}" is not in the codeunit-developer-team. If {actual_author} is an authorized developer for this codeunit you should consider defining this in the codeunit-file or adapting the name using a .mailmap-file (see https://git-scm.com/docs/gitmailmap). The developer-team-check can also be disabled using the property validate_developers_of_repository.')
221
221
 
222
222
  dependent_codeunits = self.tfcps_Tools_General.get_dependent_code_units(codeunit_file)
223
223
  for dependent_codeunit in dependent_codeunits:
@@ -236,7 +236,7 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
236
236
  self.tfcps_Tools_General.write_version_to_codeunit_file(self.get_codeunit_file(), current_codeunit_version)
237
237
 
238
238
  # set project version
239
- package_json_file = os.path.join(repository_folder, "package.json") # TDOO move this to a general project-specific (and codeunit-independent-script)
239
+ package_json_file = os.path.join(repository_folder, "package.json") # TODO move this to a general project-specific (and codeunit-independent-script)
240
240
  if os.path.isfile(package_json_file):
241
241
  package_json_data: str = None
242
242
  with open(package_json_file, "r", encoding="utf-8") as f1:
@@ -297,7 +297,7 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
297
297
  reference_folder =os.path.join( self.get_codeunit_folder(),"Other","Reference")
298
298
  class_reference_folder:str=os.path.join(reference_folder,"ReferenceContent","API")
299
299
  toc_md_file:str=os.path.join(class_reference_folder,"toc.md")
300
- GeneralUtilities.ensure_file_does_not_exist(toc_md_file)#should not be available when docfx is runninng because then toc.html will be generated from toc.md but toc.html will be generated by docfx in the target-folder
300
+ GeneralUtilities.ensure_file_does_not_exist(toc_md_file)#should not be available when docfx is running because then toc.html will be generated from toc.md but toc.html will be generated by docfx in the target-folder
301
301
 
302
302
  self.tfcps_Tools_General.generate_svg_files_from_plantuml_files_for_codeunit(self.get_codeunit_folder(), self.use_cache())
303
303
  generated_reference_folder = GeneralUtilities.resolve_relative_path("../Artifacts/Reference", reference_folder)
@@ -437,9 +437,9 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
437
437
  for file in files:
438
438
  full_source_file = os.path.join(codeunit_folder, file)
439
439
  if os.path.isfile(full_source_file):
440
- # Reson of isdir-check:
441
- # Prevent trying to copy files which are not exist.
442
- # Otherwise exceptions occurr because uncommitted deletions of files will result in an error here.
440
+ # Reason of isdir-check:
441
+ # Prevent trying to copy files which do not exist.
442
+ # Otherwise exceptions occur because uncommitted deletions of files will result in an error here.
443
443
  target_file = os.path.join(codeunit_folder, "Other", "Artifacts", "SourceCode", file)
444
444
  target_folder = os.path.dirname(target_file)
445
445
  GeneralUtilities.ensure_directory_exists(target_folder)
@@ -468,8 +468,8 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
468
468
  def __standardized_tasks_generate_coverage_report(self, repository_folder: str, codeunitname: str, generate_badges: bool, targetenvironmenttype: str, add_testcoverage_history_entry: bool = None) -> None:
469
469
  """This function expects that the file '<repositorybasefolder>/<codeunitname>/Other/Artifacts/TestCoverage/TestCoverage.xml'
470
470
  which contains a test-coverage-report in the cobertura-format exists.
471
- This script expectes that the testcoverage-reportfolder is '<repositorybasefolder>/<codeunitname>/Other/Artifacts/TestCoverageReport'.
472
- This script expectes that a test-coverage-badges should be added to '<repositorybasefolder>/<codeunitname>/Other/Resources/Badges'."""
471
+ This script expects that the testcoverage-reportfolder is '<repositorybasefolder>/<codeunitname>/Other/Artifacts/TestCoverageReport'.
472
+ This script expects that the test-coverage-badges should be added to '<repositorybasefolder>/<codeunitname>/Other/Resources/Badges'."""
473
473
  self._protected_sc.log.log("Generate testcoverage report..")
474
474
  self._protected_sc.assert_is_git_repository(repository_folder)
475
475
  codeunit_version = self.tfcps_Tools_General.get_version_of_codeunit(self.get_codeunit_file())
@@ -515,7 +515,7 @@ class TFCPS_CodeUnitSpecific_Base(ABC):
515
515
  @GeneralUtilities.check_arguments
516
516
  def __update_path_of_source_in_testcoverage_file(self, repository_folder: str, codeunitname: str) -> None:
517
517
  self._protected_sc.assert_is_git_repository(repository_folder)
518
- self._protected_sc.log.log("Update paths of source files in testcoverage files..")
518
+ self._protected_sc.log.log("Update paths of source files in testcoverage files...")
519
519
  folder = f"{repository_folder}/{codeunitname}/Other/Artifacts/TestCoverage"
520
520
  filename = "TestCoverage.xml"
521
521
  full_file = os.path.join(folder, filename)
@@ -245,15 +245,18 @@ class TFCPS_CodeUnit_BuildCodeUnits:
245
245
  "/Cache/",
246
246
  ]
247
247
  GeneralUtilities.write_lines_to_file(gitignore_file, lines)
248
+ self.sc.normalize_invisible_characters(gitignore_file)
248
249
 
249
250
  @GeneralUtilities.check_arguments
250
251
  def __ensure_global_gitignore_is_setup(self, repository_folder: str) -> None:
251
252
  """Ensures that "<repository>/.gitignore" exists and contains the expected entries."""
252
253
  gitignore_file = os.path.join(repository_folder, ".gitignore")
253
- lines = [
254
- "/.notes/",
255
- ]
256
- GeneralUtilities.write_lines_to_file(gitignore_file, lines)
254
+ GeneralUtilities.ensure_file_exists(gitignore_file)
255
+ existing_lines = GeneralUtilities.read_lines_from_file(gitignore_file)
256
+ if "/.notes/" not in existing_lines:
257
+ existing_lines.append("/.notes/")
258
+ GeneralUtilities.write_lines_to_file(gitignore_file, existing_lines)
259
+ self.sc.normalize_invisible_characters(gitignore_file)
257
260
 
258
261
 
259
262
  @GeneralUtilities.check_arguments
@@ -322,7 +325,7 @@ class TFCPS_CodeUnit_BuildCodeUnits:
322
325
  result = result+["--additionalargumentsfile", self.additionalargumentsfile]
323
326
  if not self.__use_cache:
324
327
  if self.sc.git_repository_has_uncommitted_changes(repository):
325
- self.sc.log.log("No-cache-option can not be applied because there are uncommited changes in the repository.", LogLevel.Warning)
328
+ self.sc.log.log("No-cache-option can not be applied because there are uncommitted changes in the repository.", LogLevel.Warning)
326
329
  else:
327
330
  result = result+["--nocache"]
328
331
  return result
@@ -336,7 +339,7 @@ class TFCPS_CodeUnit_BuildCodeUnits:
336
339
  - build inside the container ('scbuildcodeunitsc' or a build-pipeline): 'CustomPreCodeUnitBuildScriptInContainer.py', located in
337
340
  the folder returned by TFCPS_Tools_General.get_custom_scripts_folder_for_container(). It is searched in the folder into which
338
341
  'scbuildcodeunitsc' mounts that whole folder and - if it is not there - directly in the configuration-folder, because a
339
- build-runner usually gets the whole configuration-folder mounted instead (see the article 'Build-runner-configuration'). The
342
+ build-runner gets the TFCPS-folder of its configuration-folder mounted there instead (see the article 'Build-runner-configuration'). The
340
343
  script which the host itself runs before it starts the container is 'CustomPreCodeUnitBuildScriptForContainer.py' and is
341
344
  therefore run there and not here."""
342
345
  if self.sc.is_runnning_in_container():
@@ -370,6 +373,13 @@ class TFCPS_CodeUnit_BuildCodeUnits:
370
373
 
371
374
  @GeneralUtilities.check_arguments
372
375
  def build_codeunits_in_container(self,base_mount_folder:str) -> tuple[bool, str]:
376
+ """Runs scbuildcodeunits (with the options of this object) inside the SCBuilder-image and returns whether it succeeded and
377
+ its output. A failing build is reported by the result and not by an exception.
378
+ base_mount_folder is mounted into the container and must be the repository itself or a folder which contains it (for
379
+ example to make the real git-folder of a submodule available); otherwise a ValueError is raised.
380
+ Before the container is started the optional script "CustomPreCodeUnitBuildScriptForContainer.py" of the configuration-folder
381
+ is run on the host and the newest ScriptCollection is installed inside the container. See the article "Configuration-folder"
382
+ of the reference for what is mounted into the container."""
373
383
  container_base_mount_folder, container_repository_folder = self.__get_folders_inside_container(base_mount_folder)
374
384
 
375
385
  #build the scbuildcodeunits-arguments based on the current state (analogous to the arguments accepted by the scbuildcodeunits-executable). each token must be a separate argument because run_program_argsasarray passes every list-element verbatim and does not split on spaces.
@@ -623,7 +633,7 @@ class TFCPS_CodeUnit_BuildCodeUnits:
623
633
  )
624
634
  diagram_svg_file=os.path.join(self.repository,"Other","Reference","Technical","Diagrams",f"{filenamebase}.svg")
625
635
  GeneralUtilities.ensure_file_exists(diagram_svg_file)
626
- GeneralUtilities.assert_condition(not self.sc.file_is_git_ignored(f"Other/Reference/Technical/Diagrams/{filenamebase}.svg",self.repository),f"Other/Reference/Technical/Diagrams/{filenamebase}.svg must not be git-ignored")#because it should be referencable in markdown-files and viewable without building the codeunits.
636
+ GeneralUtilities.assert_condition(not self.sc.file_is_git_ignored(f"Other/Reference/Technical/Diagrams/{filenamebase}.svg",self.repository),f"Other/Reference/Technical/Diagrams/{filenamebase}.svg must not be git-ignored")#because it should be referenceable in markdown-files and viewable without building the codeunits.
627
637
  self.sc.generate_chart_diagram(diagram_definition_file,os.path.basename(diagram_svg_file))
628
638
  self.sc.add_tooltips_to_chart_diagram(diagram_svg_file)#so the exact values of a data-point are visible when the svg-file is opened directly in a browser
629
639
  self.sc.format_xml_file(diagram_svg_file)
@@ -733,6 +743,12 @@ class TFCPS_CodeUnit_BuildCodeUnits:
733
743
 
734
744
  @GeneralUtilities.check_arguments
735
745
  def update_dependencies(self) -> None:
746
+ """Updates the dependencies of all codeunits of the repository by building them with a hook which updates the dependencies
747
+ of each codeunit before it is built. The repository must not have uncommitted changes (otherwise a ValueError is raised).
748
+ If the update changed anything, a changelog-entry for the current project-version is created if it does not exist yet, all
749
+ codeunits are built again to verify that they are buildable with all updates together, and all changes are committed
750
+ ("Updated dependencies"). A failing build raises an exception and leaves the changes uncommitted.
751
+ Side-effect: the year in the license-file is updated as well."""
736
752
  repository=self.repository
737
753
  self.sc.log.log("Update dependencies for product...")
738
754
  self.update_year_in_license_file()
@@ -76,7 +76,7 @@ class TFCPS_CreateRelease:
76
76
  branch_to_be_released_commit_id = self.sc.git_get_commit_id(tfcps_CreateReleaseConfiguration.repository, tfcps_CreateReleaseConfiguration.branch_to_be_released)
77
77
  main_branch_commit_id = self.sc.git_get_commit_id(tfcps_CreateReleaseConfiguration.repository, tfcps_CreateReleaseConfiguration.main_branch)
78
78
  if branch_to_be_released_commit_id == main_branch_commit_id:
79
- self.sc.log.log("Merge to main-branch will not be done because there are no changed which can be merged.")
79
+ self.sc.log.log("Merge to main-branch will not be done because there are no changes which can be merged.")
80
80
  else:
81
81
  self.sc.log.log("Merge to main-branch...",LogLevel.Information)
82
82
  mergeToMainConfiguration:MergeToMainConfiguration=MergeToMainConfiguration(tfcps_CreateReleaseConfiguration.current_file,tfcps_CreateReleaseConfiguration.product_name,tfcps_CreateReleaseConfiguration.product_name,tfcps_CreateReleaseConfiguration.branch_to_be_released,tfcps_CreateReleaseConfiguration.log_level,tfcps_CreateReleaseConfiguration.additional_arguments_file,tfcps_CreateReleaseConfiguration.main_branch,tfcps_CreateReleaseConfiguration.common_remote_name,tfcps_CreateReleaseConfiguration.build_repository)
@@ -86,7 +86,7 @@ class TFCPS_CreateRelease:
86
86
  main_branch_commit_id = self.sc.git_get_commit_id(tfcps_CreateReleaseConfiguration.repository, tfcps_CreateReleaseConfiguration.main_branch)
87
87
  stable_branch_commit_id = self.sc.git_get_commit_id(tfcps_CreateReleaseConfiguration.repository, tfcps_CreateReleaseConfiguration.stable_branch)
88
88
  if main_branch_commit_id == stable_branch_commit_id:
89
- self.sc.log.log("Merge to stable-branch will not be done because there are no changed which can be released.")
89
+ self.sc.log.log("Merge to stable-branch will not be done because there are no changes which can be released.")
90
90
  else:
91
91
  self.sc.log.log("Merge to stable-branch...",LogLevel.Information)
92
92
  mergeToStableConfiguration:MergeToStableConfiguration=MergeToStableConfiguration(tfcps_CreateReleaseConfiguration.log_level,tfcps_CreateReleaseConfiguration.main_branch,tfcps_CreateReleaseConfiguration.stable_branch,tfcps_CreateReleaseConfiguration.repository,tfcps_CreateReleaseConfiguration.build_repository,tfcps_CreateReleaseConfiguration.common_remote_name,tfcps_CreateReleaseConfiguration.build_repo_main_branch_name,tfcps_CreateReleaseConfiguration.reference_repo_main_branch_name,tfcps_CreateReleaseConfiguration.reference_remote_name,tfcps_CreateReleaseConfiguration.build_repo_remote_name,tfcps_CreateReleaseConfiguration.artifacts_target_folder,tfcps_CreateReleaseConfiguration.common_remote_url,tfcps_CreateReleaseConfiguration.additional_arguments_file)