Feat: Add Sogou Text Backend

[scarletkc]

Feature

• add ddgs/engines/sogou.py implementing text search with timelimit + pagination support
• wire the backend into CLI (ddgs text -b sogou) and list it in README’s engines table
• results/downloads expose the real destination URLs

Notes

• endpoint: https://www.sogou.com/web (GET)
• selectors: items_xpath = //div[contains(@class,'vrwrap') and not(contains(@class,'hint'))]
• _normalize_href follows redirects via inline JS/meta refresh and caches the decoded hrefs

Tests

• pytest tests/ → 17/18 (pre-existing test_books_command failure)
• pre-commit run --all-files
• manual DDGS().text('python', backend='sogou', max_results=5)

[scarletkc]

@deedy5 Sogou is a well-known search engine in China. Because of the GFW, many users hope to use ddgs without a proxy, but none of the existing search backends support this. This backend addresses that gap and makes ddgs usable in China.

Occasionally, the first result may be missing (since it is Sogou’s own sponsored recommendation), but this has little impact on overall functionality.

[deedy5]

Thanks for the contribution — your other changes look good. Could you please revert the last commit that modified .gitignore and README? Those edits aren’t necessary and should be left unchanged.

[scarletkc]

Thanks for the contribution — your other changes look good. Could you please revert the last commit that modified .gitignore and README? Those edits aren’t necessary and should be left unchanged.

Reverted now. Thanks!

[deedy5]

@scarletkc
We require direct, unencoded URLs (not redirect/wrapper links like https://www.sogou.com/link?url=...)

[deedy5]

Please remove the tests: they don't make sense in their current form.

[deedy5]

please delete from __future__ import annotations

[deedy5]

"href": use xpath from _data_url_xpath

[deedy5]

function is unnecessary

[deedy5]

function is unnecessary

[deedy5]

function is unnecessary

[deedy5]

def extract_results is unnecessary

[deedy5]

del _data_url_xpath

[deedy5]

validate href in post_extract_results

[deedy5]

Everything works—thanks!
Could you optimize the code and rename the branch containing your changes to a name other than 'main'?
You only need to implement the correct xpath's and functions build_payload and post_extract_results.
Check Contributing.md and how the BaseSearchEngine class — the one Sogou inherits from — works:

ddgs/ddgs/base.py

Lines 19 to 122 in 7962c03

	class BaseSearchEngine(ABC, Generic[T]):
	"""Abstract base class for all search-engine backends."""
	name: ClassVar[str] # unique key, e.g. "google"
	category: ClassVar[Literal["text", "images", "videos", "news", "books"]]
	provider: ClassVar[str] # source of the search results (e.g. "bing" for DuckDuckgo)
	disabled: ClassVar[bool] = False # if True, the engine is disabled
	priority: ClassVar[float] = 1
	search_url: str
	search_method: ClassVar[str] # GET or POST
	search_headers: ClassVar[Mapping[str, str]] = {}
	items_xpath: ClassVar[str]
	elements_xpath: ClassVar[Mapping[str, str]]
	elements_replace: ClassVar[Mapping[str, str]]
	def __init__(self, proxy: str | None = None, timeout: int | None = None, *, verify: bool | str = True) -> None:
	self.http_client = HttpClient(proxy=proxy, timeout=timeout, verify=verify)
	self.results: list[T] = []
	@property
	def result_type(self) -> type[T]:
	"""Get result type based on category."""
	categories = {
	"text": TextResult,
	"images": ImagesResult,
	"videos": VideosResult,
	"news": NewsResult,
	"books": BooksResult,
	}
	return categories[self.category]
	@abstractmethod
	def build_payload(
	self,
	query: str,
	region: str,
	safesearch: str,
	timelimit: str | None,
	page: int,
	**kwargs: str,
	) -> dict[str, Any]:
	"""Build a payload for the search request."""
	raise NotImplementedError
	def request(self, *args: Any, **kwargs: Any) -> str | None: # noqa: ANN401
	"""Make a request to the search engine."""
	resp = self.http_client.request(*args, **kwargs)
	if resp.status_code == 200:
	return resp.text
	return None
	@cached_property
	def parser(self) -> LHTMLParser:
	"""Get HTML parser."""
	return LHTMLParser(remove_blank_text=True, remove_comments=True, remove_pis=True, collect_ids=False)
	def extract_tree(self, html_text: str) -> html.Element:
	"""Extract html tree from html text."""
	return html.fromstring(html_text, parser=self.parser)
	def pre_process_html(self, html_text: str) -> str:
	"""Pre-process html_text before extracting results."""
	return html_text
	def extract_results(self, html_text: str) -> list[T]:
	"""Extract search results from html text."""
	html_text = self.pre_process_html(html_text)
	tree = self.extract_tree(html_text)
	items = tree.xpath(self.items_xpath)
	results = []
	for item in items:
	result = self.result_type()
	for key, value in self.elements_xpath.items():
	data = " ".join(x.strip() for x in item.xpath(value))
	result.__setattr__(key, data)
	results.append(result)
	return results
	def post_extract_results(self, results: list[T]) -> list[T]:
	"""Post-process search results."""
	return results
	def search(
	self,
	query: str,
	region: str = "us-en",
	safesearch: str = "moderate",
	timelimit: str | None = None,
	page: int = 1,
	**kwargs: str,
	) -> list[T] | None:
	"""Search the engine."""
	payload = self.build_payload(
	query=query, region=region, safesearch=safesearch, timelimit=timelimit, page=page, **kwargs
	)
	if self.search_method == "GET":
	html_text = self.request(self.search_method, self.search_url, params=payload, headers=self.search_headers)
	else:
	html_text = self.request(self.search_method, self.search_url, data=payload, headers=self.search_headers)
	if not html_text:
	return None
	results = self.extract_results(html_text)
	return self.post_extract_results(results)