Metadata-Version: 2.4
Name: foxange
Version: 0.4.0
Summary: A custom Python module collection
Author-email: foxange <slcfox@foxmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## foxange ，一个Python第三方库😊

### 目录

- 下载
- foxange的文件结构
- 如何使用函数和函数的特殊注意🤔
  - `__init__.py`
  - `math.py`
  - `input.py`
  - `list_proce.py`
  - `file.py`
- 声明和其他
- 感谢和致谢

---

### 下载

```pip install foxange```

---

## foxange的文件结构

```file
file
foxange
│  .gitignore
│  LICENSE
│  pyproject.toml
│  README.md
│  test.txt
│
├─.github
│  └─workflows
│          publish.yml
│
├─dist
│      foxange-0.3.3-py3-none-any.whl
│      foxange-0.3.3.tar.gz
│
├─src
│  ├─foxange
│  │  │  file.py
│  │  │  input.py
│  │  │  list_proce.py
│  │  │  math.py
│  │  │  test.txt
│  │  │  __init__.py
│  │  │
│  │  └─__pycache__
│  │          input.cpython-311.pyc
│  │          __init__.cpython-311.pyc
│  │
│  └─foxange.egg-info
│          dependency_links.txt
│          PKG-INFO
│          SOURCES.txt
│          top_level.txt
│
└─tests
        files.txt
        test1.py
        test2.py
```

---

## 如何使用函数和函数的特殊注意🤔

### `__init__.py`

- `get_help()->None`

  这个是获取foxange第三方库的帮助,在 **实际开发** 中请不要使用它

  代码示例:

  ```Python
  >>> import foxange
  >>> foxange.get_help()
  ... #这里省略
  ```

- `version()->str`

  这是一个返回你在使用的foxange版本函数,在 **实际开发** 中请不要使用它

  代码示例:

  ```cmd
  C:\> pip install foxange==0.1.0
  ... 省略
  ```

  ``` Python
  >>> import foxange
  >>> foxange.version()
  '0.1.0'
  ```

  注意,这个函数在0.3.3以后(不包含0.3.3)都不输出`version : {version}` 文字了

------

## `math.py`

- `is_prime(number: int) -> bool`
  判断一个整数是否为素数。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_prime(7))
  print(foxange.math.is_prime(10))
  '''
  结果:
  True
  False
  '''
  ```

  

- `is_composite_number(number: int) -> bool`
  判断一个整数是否为合数（大于1且不是素数）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_composite_number(9))
  print(foxange.math.is_composite_number(2))
  '''
  结果:
  True
  False
  '''
  ```

  

- `pow(number1: float, number2: float) -> float`
  幂运算，返回 `number1 ** number2`。
  **注意**：会覆盖 Python 内置 `pow()`，如需内置请用 `__builtins__.pow`。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.pow(2, 3))
  '''
  结果:
  8.0
  '''
  ```

  

- `radical_sign(number: int, inx: int = 2) -> float`
  求 `number` 的 `inx` 次方根（默认平方根）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.radical_sign(16))
  print(foxange.math.radical_sign(27, 3))
  '''
  结果:
  4.0
  3.0
  '''
  ```

  

- `factor(number: int, key=lambda x: True, recur: bool = False) -> list[int]`
  返回 `number` 的所有因子。

  - `key`：过滤函数，只有 `key(i)` 为 `True` 的因子才加入。
  - `recur`：若为 `True`，平方根因子会被添加两次（`i` 和 `j` 都加入）。
    **注意**：`recur=True` 会使完全平方数的平方根因子出现两次。
    **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.factor(12))
  print(foxange.math.factor(12, key=lambda x: x % 2 == 0))
  print(foxange.math.factor(16, recur=True))
  '''
  结果:
  [1, 2, 3, 4, 6, 12]
  [2, 4, 6, 12]
  [1, 2, 2, 4, 8, 16]
  '''
  ```

  

- `prime_factors(n: int) -> list[int]`
  返回 `n` 的所有质因子（包含重复次数）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.prime_factors(12))
  print(foxange.math.prime_factors(18))
  '''
  结果:
  [2, 2, 3]
  [2, 3, 3]
  '''
  ```

  

- `sum(*values)`
  增强求和函数，支持数字和列表混合。
  **注意**：会覆盖内置 `sum()`，如需内置请用 `__builtins__.sum`。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.sum(1, 2, [3, 4], 5))
  '''
  结果:
  15
  '''
  ```

  

- `digit_separation(number: int) -> list`
  将整数按位拆分为数字列表。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.digit_separation(12345))
  '''
  结果:
  [1, 2, 3, 4, 5]
  '''
  ```

  

- `is_perfect_number(number: int) -> bool`
  判断是否为完全数（真因子和等于自身）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_perfect_number(6))
  print(foxange.math.is_perfect_number(12))
  '''
  结果:
  True
  False
  '''
  ```

  

- `is_excess_number(number: int) -> bool`
  判断是否为过剩数（真因子和大于自身）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_excess_number(12))
  '''
  结果:
  True
  '''
  ```

  

- `is_deficit(number: int) -> bool`
  判断是否为亏数（真因子和小于自身）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_deficit(4))
  '''
  结果:
  True
  '''
  ```

  

- `is_amicable_numbers(number1: int, number2: int) -> bool`
  判断两个数是否为亲和数（彼此的真因子和相等）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_amicable_numbers(220, 284))
  '''
  结果:
  True
  '''
  ```

  

- `is_engagements_number(number1: int, number2: int) -> bool`
  判断两个数是否为订婚数（除去1和自身的真因子和相等）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_engagements_number(48, 75))
  '''
  结果:
  True
  '''
  ```

  

- `is_smith_number(number: int) -> bool`
  判断是否为 Smith 数（合数，各位数字之和等于所有质因子（含重复）的各位数字之和）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_smith_number(4))
  print(foxange.math.is_smith_number(22))
  '''
  结果:
  True
  False
  '''
  ```

  

- `is_niven_number(number: int) -> bool`
  判断是否为 Harshad 数（能被其各位数字之和整除）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_niven_number(18))
  '''
  结果:
  True
  '''
  ```

  

- `is_moran_number(number: int) -> bool`
  判断是否为 Moran 数（Harshad 数，且商为素数）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_moran_number(18))
  print(foxange.math.is_moran_number(27))
  '''
  结果:
  False
  True
  '''
  ```

  

- `is_self_power_number(number: int) -> bool`
  判断是否为自幂数（每位数字的位数次幂之和等于自身）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_self_power_number(153))
  print(foxange.math.is_self_power_number(9474))
  '''
  结果:
  True
  True
  '''
  ```

  

- `is_narcissus_number(number: int) -> bool`
  判断是否为水仙花数（三位自幂数）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_narcissus_number(153))
  print(foxange.math.is_narcissus_number(9474))
  '''
  结果:
  True
  False
  '''
  ```

  

- `is_palindrome_number(number: int) -> bool`
  判断是否为回文数。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_palindrome_number(12321))
  print(foxange.math.is_palindrome_number(12345))
  '''
  结果:
  True
  False
  '''
  ```

  

- `is_reversible_prime(number: int) -> bool`
  判断是否为可逆素数（本身为素数，反转后也是素数且不同）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.is_reversible_prime(13))
  print(foxange.math.is_reversible_prime(11))
  '''
  结果:
  True
  False
  '''
  ```

  

- `gcd(a: int, b: int) -> int`
  最大公约数。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.gcd(48, 18))
  '''
  结果:
  6
  '''
  ```

  

- `lcm(a: int, b: int) -> int`
  最小公倍数。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.lcm(12, 18))
  '''
  结果:
  36
  '''
  ```

  

- `factorial(n: int) -> int`
  阶乘。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.factorial(5))
  '''
  结果:
  120
  '''
  ```

  

- `isqrt(n: int) -> int`
  整数平方根（向下取整）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.isqrt(10))
  '''
  结果:
  3
  '''
  ```

  

- `reverse_int(n: int) -> int`
  反转整数，保留符号。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.reverse_int(12345))
  print(foxange.math.reverse_int(-678))
  '''
  结果:
  54321
  -876
  '''
  ```

  

- `bin_to_int(bin_str: str) -> int`
  二进制字符串转整数。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.bin_to_int("1010"))
  '''
  结果:
  10
  '''
  ```

  

- `int_to_bin(n: int) -> str`
  整数转二进制字符串（不带 `0b` 前缀）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.int_to_bin(10))
  '''
  结果:
  "1010"
  '''
  ```

  

- `digits_count(n: int) -> int`
  返回整数的位数（0 算 1 位）。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.digits_count(0))
  print(foxange.math.digits_count(12345))
  '''
  结果:
  1
  5
  '''
  ```

  

- `combination(n: int, k: int) -> int`
  组合数 C(n, k)。
  **代码示例**：

  ```Python
  import foxange
  
  print(foxange.math.combination(5, 2))
  '''
  结果:
  10
  '''
  ```

## `input.py`

- `collect_input(*value)->list`

  这是一个一次性输入多个输入的函数,返回一个列表

  代码示例:

  ```Python
  import foxange
  print(foxange.input.collect_input("name>","age>"))
  '''
  结果:
  name> 张三
  age> 20
  ['张三' , '20']
  '''
  ```

  **注意** : 如果`*value`是一个或多个列表,`collect_input`会直接类成似于`input([1,2,3,4])`差不多的效果

- `sanitize_input(text:str,*strings)->str`

  这是一个删除`text`字符串中所有的`*strings`子字符串

  代码示例:

  ```Python
  import foxange
  string = "hello world!"
  print(foxange.input.sanitize_input(text=string,'h','o'))
  '''
  结果:
  ell wrld!
  '''
  ```

  **注意** : 在让这个函数导入`text` 形参时,务必使用:`text=...`否则会有问题

- `numeric_input(text:str,min:int,max:int,netvalid:Any=None)->Any`

  这是一个判断`input(text)`字符串的长度是否**大于等于`min`**或**小于等于`max`**

  代码示例:

  ```Python
  import foxange
  foxange.input.numeric_input(text="请输入一个长度大于等于5小于等于1的字符串> ",min=1,max=5,notvalid="你输入错了!😠")
  '''
  结果:
  请输入一个长度大于等于5小于等于1的字符串> 4874964345465488
  你输入错了!😠
  '''
  ```

- `choice_input(title:str,value:list,input_text:str)->list`

  这是一个类似于这个:

  ```
  title
  1.~~~
  2.
  input>
  ```

  的函数,也可以说是还原了这个功能 并返回一个`[参数在value中的位置,这个值]`的列表

  代码示例:

  ```Python
  import foxange
  print(foxange.input.choive_input("菜单",['hi','bye'],"选择>"))
  '''
  结果:
  菜单
  1. hi
  2. bye
  选择>1
  [0,'hi']
  '''
  ```

  ~~我都不知道这个东西有什么用~~

- `confrim(text:str,yes_str:list=["yes"],no_str:list=["no"])->Any`:

  一个类似于Python tkinter的askyesno的东西

  代码示例:

  ```Python
  import foxange
  print(foxange.input.confirm("你确定要退出吗?",yes_str=["yes",'y'],no_str=['no','n']))
  '''
  结果:
  你确定要退出吗?[yes/no]yes
  True
  '''
  ```

  **注意** : 在`[]`中,他只会显示`yes_str`和`no_str`的第一项,如果是`no_str`的则返回`True`,如果是`yes_str`的,返回`False`,什么都不是返回`None`,**`yes_str`会比`no_str`优先判断!**

## `list_proce.py`

- `remove(value:list,condition=None)->list`

  删除满足条件的值,这个`condition`**必须是`None`或`lambda`表达式!!!**

  代码示例:

  ```Python
  import foxange
  print(foxange.list_proce.remove(value=[1,2,3,4,5,6],condition=lambda x:x%2==0)) #删除所有的偶数
  '''
  结果:
  [1,3,5]
  '''
  ```

- `unique(value:list)->list`

  是给一个变量去重用的

  代码示例:

  ```Python
  import foxange
  print(foxange.list_proce.unique([1,1,2,3]))
  '''
  结果:
  [1,2,3]
  '''
  ```

- `rotate(value:list,inx:int)->list`

  将列表`value`向右旋`inx`步数

  代码示例:

  ```Python
  import foxange
  print(foxange.list_proce.rotate([1,2,3,4],1))
  '''
  结果:
  [4,1,2,3]
  '''
  ```

  **注意** : **如果旋转步数是 0 或列表长度的整数倍，则返回原列表的副本**

- `sqread(*args)->tuple`

  `spread` 函数用于将传入的参数“展开”成一个元组。

  - 如果某个参数是列表或元组，就会将其元素逐一取出添加到结果中；
  - 如果参数是其他类型的值，则直接添加到结果中。

  最终返回一个元组（不可变序列）。

  **示例**：

  ```Python
  from foxange.list_proce import spread
  
  result = spread([1, 2], 3, (4, 5), "hello")
  print(result)  
  '''
  结果:
  (1, 2, 3, 4, 5, 'hello')
  '''
  ```

  它常用于需要将多个可能嵌套的可迭代对象合并成一个扁平元组的场景。

## `file.py`

- `input_to_file(*value, path, mode='w', end='', sep='\n') -> None`
  将传入的多个字符串按 `sep` 拼接，末尾加上 `end`，写入指定文件。支持写入模式（`'w'` 覆写，`'a'` 追加）。
  **代码示例**：

  ```Python
  import foxange
  
  foxange.file.input_to_file("hello", "world", path="test.txt", sep=",", end="!")
  # 文件内容: hello,world!
  '''
  结果:
  (无返回值，文件被写入)
  '''
  ```

  

- `read_lines(path: str, strip_newline: bool = True, encoding: str = 'utf-8') -> List[str]`
  读取文件所有行，默认去除末尾换行符。
  **代码示例**：

  ```Python
  import foxange
  
  lines = foxange.file.read_lines("test.txt")
  print(lines)
  '''
  结果:
  ['hello,world!']
  '''
  ```

  

- `write_lines(path: str, lines: List[str], mode: str = 'w', encoding: str = 'utf-8') -> None`
  将字符串列表写入文件，每行自动添加换行符。自动创建缺失的父目录。
  **代码示例**：

  ```Python
  import foxange
  
  foxange.file.write_lines("output.txt", ["first", "second"], mode='w')
  '''
  结果:
  (文件 output.txt 包含两行: first 和 second)
  '''
  ```

  

- `tail(path: str, n: int = 10, encoding: str = 'utf-8') -> List[str]`
  高效读取文件最后 `n` 行（按字节倒查，适合大文件）。
  **代码示例**：

  ```Python
  import foxange
  
  last = foxange.file.tail("test.txt", n=1)
  print(last)
  '''
  结果:
  ['hello,world!']
  '''
  ```

  

- `head(path: str, n: int = 10, encoding: str = 'utf-8') -> List[str]`
  读取文件前 `n` 行。
  **代码示例**：

  ```Python
  import foxange
  
  first = foxange.file.head("test.txt", n=1)
  print(first)
  '''
  结果:
  ['hello,world!']
  '''
  ```

  

- `safe_read_json(path: str, default: Any = None) -> Any`
  安全读取 JSON 文件。若文件不存在或 JSON 无效，返回 `default`。
  **代码示例**：

  ```Python
  import foxange
  
  data = foxange.file.safe_read_json("config.json", default={})
  print(data)
  '''
  结果:
  {}   (假设文件不存在或无效)
  '''
  ```

  

- `safe_write_json(path: str, data: Any, indent: int = 2) -> None`
  将数据写入 JSON 文件，自动创建父目录，支持非 ASCII 字符。
  **代码示例**：

  ```Python
  import foxange
  
  foxange.file.safe_write_json("data.json", {"name": "foxange", "version": "0.4.0"})
  '''
  结果:
  (生成 data.json 文件)
  '''
  ```

  

- `get_file_size(path: str, human_readable: bool = False) -> Union[int, str]`
  返回文件大小（字节）。若 `human_readable=True`，转换为 B/KB/MB 等易读格式。
  **代码示例**：

  ```Python
  import foxange
  
  size = foxange.file.get_file_size("test.txt")
  print(size)
  size_hr = foxange.file.get_file_size("test.txt", human_readable=True)
  print(size_hr)
  '''
  结果:
  12
  '12.0 B'
  '''
  ```

  

- `ensure_dir(path: str) -> None`
  创建目录（如果不存在），相当于 `os.makedirs(path, exist_ok=True)`。
  **代码示例**：

  ```Python
  import foxange
  
  foxange.file.ensure_dir("./new_folder/sub")
  '''
  结果:
  (目录被创建，无返回值)
  '''
  ```

  

- `atomic_write(path: str, data: Union[str, bytes], mode: str = 'w', encoding: str = 'utf-8') -> None`
  原子写入：先写入临时文件，再替换目标文件，避免写入中途崩溃导致文件损坏。
  **注意**：Windows 下若目标文件被其他进程打开，`os.replace` 可能失败。
  **代码示例**：

  ```Python
  import foxange
  
  foxange.file.atomic_write("important.txt", "critical data")
  '''
  结果:
  (文件被安全写入)
  '''
  ```

  

- `find_files(directory: str, pattern: str = '*', recursive: bool = True) -> List[str]`
  查找目录下匹配通配符 `pattern` 的文件，返回相对路径列表。支持 `*` 和 `?`（`fnmatch` 规则）。
  **代码示例**：

  ```Python
  import foxange
  
  all_py = foxange.file.find_files(".", "*.py", recursive=True)
  print(all_py)
  '''
  结果:
  ['input.py', 'list_proce.py', 'math.py', 'file.py', ...]
  '''
  ```

---

## 声明和其他

如果你发现了问题,请给

`foxangePyPI@outlook.com`发送问题

发送格式: `函数`   `问题`    `你的代号` 我们会在这个文件里记录你的名字,从而感谢你对foxange第三方库的贡献和支持!

**foxange** 第三方库开源github链接 - [foxange-org/PyPI-foxange]([foxange-org/PyPI-foxange： foxange的python第三方库](https://github.com/foxange-org/PyPI-foxange))

---

## 感谢和致谢

这里放着所有找bug和帮助完成foxange第三方库的所有人(这些人都是在这个版本之前提交的)

| 代号 | 邮箱 | 时间 | 版本 | 函数 | 问题 | 严重程度 |
| :--: | :--: | :--: | :--: | :--: | :--: | -------- |
|      |      |      |      |      |      |          |

